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 37 22 0a 23 64 65 66 69 6e 65 20 53 .7.17".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 37 0a 23 64 65 MBER 3007017.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33 CE_ID "2013
1070: 2d 30 35 2d 31 36 20 31 32 3a 34 31 3a 34 39 20 -05-16 12:41:49
1080: 36 64 34 35 61 37 39 66 62 31 38 64 63 64 33 30 6d45a79fb18dcd30
1090: 35 63 63 34 31 63 35 32 35 30 36 30 65 34 32 66 5cc41c525060e42f
10a0: 32 34 30 32 62 64 37 37 22 0a 0a 2f 2a 0a 2a 2a 2402bd77"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 library instead
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a le. ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ro. ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 ing constant. T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 ion is provided
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 for use in DLLs
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 since DLL users
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 onstants within
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a the DLL. ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 n integer equal
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 RSION_NUMBER].
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 .** indicating
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 defined at .**
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e compile time. ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ). .**.** ^The
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 string. ^If N
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 ileoption_get()
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 ointer. ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 on_get()..**.**
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 EF: Test To See
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 f.** SQLite was
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 me option being
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 set to 0..**.**
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 ithout mutexes.
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 mutexes.** are
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b . When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 re omitted. Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 e thread..**.**
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 penalty..** So
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 he mutexes. But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 behavior is for
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 Lite that it is
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 linking against
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 setting of the
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 only reports on
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 g. If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 disabled using
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 e3_config()].**
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 ITHREAD],.** or
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 UTEX]. ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 ead safety, not
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 ting made by.**
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 threadsafe().**
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 is unchanged by
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 med "sqlite3".
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 It is useful to
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 s an object. Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 structors. Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 te_function()],
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 busy_timeout()]
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 64-Bit Integer
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 S: sqlite_int64
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 n store integer
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 372036854775807
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 inclusive. ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 ues .** between
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c PE. typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 qlite_int64;. t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e ). typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 e. typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 _int64;. typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 f unsigned long
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 _uint64;../*.**
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 eturn SQLITE_OK
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ated..**.** ^If
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 close().** will
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 QLITE_BUSY]..**
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 e3_backup is.**
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 finished. The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 guages that are
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 ize | finalize]
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 backup_finish |
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 ject. ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2fc0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 is called on a
2fd0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2fe0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c tion] that still
2ff0: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 has.** outstand
3000: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 ing [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f handles], and/o
3030: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 r.** [sqlite3_ba
3040: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 ckup] objects th
3050: 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 en it returns SQ
3060: 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 LITE_OK but the
3070: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 deallocation.**
3080: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 of resources is
3090: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
30a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ll [prepared sta
30b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 tements], [BLOB
30c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 handles],.** and
30d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
30e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c ] objects are al
30f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a so destroyed..**
3100: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 .** ^If an [sqli
3110: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 te3] object is d
3120: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 estroyed while a
3130: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
3140: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 open,.** the tra
3150: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
3160: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
3170: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 back..**.** The
3180: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 C parameter to
3190: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
31a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
31b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 close_v2(C)].**
31c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 must be either a
31d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
31e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d or an [sqlite3]
31f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 object pointer
3200: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
3210: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
3220: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
3230: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 16()], or.** [sq
3240: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
3250: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f , and not previo
3260: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 usly closed..**
3270: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 ^Calling sqlite3
3280: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 _close() or sqli
3290: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 te3_close_v2() w
32a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
32b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 er.** argument i
32c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
32d0: 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 op..*/.SQLITE_AP
32e0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c I int sqlite3_cl
32f0: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 ose(sqlite3*);.S
3300: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 lite3_close_v2(s
3320: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
3330: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 The type for a
3340: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
3350: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 n..** This is le
3360: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 gacy and depreca
3370: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c ted. It is incl
3380: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 uded for histori
3390: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 cal.** compatibi
33a0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 lity and is not
33b0: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 documented..*/.t
33c0: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c ypedef int (*sql
33d0: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 ite3_callback)(v
33e0: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c oid*,int,char**,
33f0: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a char**);../*.**
3400: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 CAPI3REF: One-S
3410: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 tep Query Execut
3420: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a ion Interface.**
3430: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
3440: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 exec() interface
3450: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 is a convenienc
3460: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 e wrapper around
3470: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
3480: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c pare_v2()], [sql
3490: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e ite3_step()], an
34a0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c d [sqlite3_final
34b0: 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 ize()],.** that
34c0: 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 allows an applic
34d0: 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c ation to run mul
34e0: 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 tiple statements
34f0: 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f of SQL.** witho
3500: 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 ut having to use
3510: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 a lot of C code
3520: 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 . .**.** ^The sq
3530: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
3540: 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f erface runs zero
3550: 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 or more UTF-8 e
3560: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 ncoded,.** semic
3570: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 olon-separate SQ
3580: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 L statements pas
3590: 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 sed into its 2nd
35a0: 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e argument,.** in
35b0: 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 the context of
35c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
35d0: 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 nnection] passed
35e0: 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a in as its 1st.*
35f0: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 * argument. ^If
3600: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 the callback fu
3610: 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 nction of the 3r
3620: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
3630: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3640: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
3650: 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 n it is invoked
3660: 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 for each result
3670: 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 row.** coming ou
3680: 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 t of the evaluat
3690: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
36a0: 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 s. ^The 4th arg
36b0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 ument to.** sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 te3_exec() is re
36d0: 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f layed through to
36e0: 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e the 1st argumen
36f0: 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c t of each.** cal
3700: 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e lback invocation
3710: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 . ^If the callb
3720: 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 ack pointer to s
3730: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
3740: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e is NULL, then n
3750: 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 o callback is ev
3760: 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 er invoked and r
3770: 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a esult rows are.*
3780: 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a * ignored..**.**
3790: 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 ^If an error oc
37a0: 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 curs while evalu
37b0: 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 ating the SQL st
37c0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 atements passed
37d0: 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f into.** sqlite3_
37e0: 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 exec(), then exe
37f0: 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 cution of the cu
3800: 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 rrent statement
3810: 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 stops and.** sub
3820: 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e sequent statemen
3830: 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 ts are skipped.
3840: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 ^If the 5th par
3850: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3860: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 3_exec().** is n
3870: 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 ot NULL then any
3880: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 error message i
3890: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d s written into m
38a0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a emory obtained.*
38b0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
38c0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 malloc()] and pa
38d0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 ssed back throug
38e0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 h the 5th parame
38f0: 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 ter..** To avoid
3900: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 memory leaks, t
3910: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
3920: 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 hould invoke [sq
3930: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a lite3_free()].**
3940: 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 on error messag
3950: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e e strings return
3960: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 ed through the 5
3970: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a th parameter of.
3980: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 ** of sqlite3_ex
3990: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 ec() after the e
39a0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
39b0: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 ing is no longer
39c0: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 needed..** ^If
39d0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
39e0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
39f0: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 c() is not NULL
3a00: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a and no errors.**
3a10: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c occur, then sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 ite3_exec() sets
3a30: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 the pointer in
3a40: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 its 5th paramete
3a50: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 r to.** NULL bef
3a60: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a ore returning..*
3a70: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 *.** ^If an sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3a90: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
3aa0: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 zero, the sqlite
3ab0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 3_exec().** rout
3ac0: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 ine returns SQLI
3ad0: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 TE_ABORT without
3ae0: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 invoking the ca
3af0: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 llback again and
3b00: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e .** without runn
3b10: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 ing any subseque
3b20: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 nt SQL statement
3b30: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e s..**.** ^The 2n
3b40: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
3b50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3b60: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
3b70: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d on is the.** num
3b80: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
3b90: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e n the result. ^
3ba0: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 The 3rd argument
3bb0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
3bc0: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 exec().** callba
3bd0: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ck is an array o
3be0: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 f pointers to st
3bf0: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 rings obtained a
3c00: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 s if from.** [sq
3c10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
3c20: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 t()], one for ea
3c30: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 ch column. ^If
3c40: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a an element of a.
3c50: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 ** result row is
3c60: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 NULL then the c
3c70: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 orresponding str
3c80: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 ing pointer for
3c90: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 the.** sqlite3_e
3ca0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 xec() callback i
3cb0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
3cc0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 . ^The 4th argu
3cd0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 ment to the.** s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
3cf0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 llback is an arr
3d00: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
3d10: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 o strings where
3d20: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 each.** entry re
3d30: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d presents the nam
3d40: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 e of correspondi
3d50: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ng result column
3d60: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 as obtained.**
3d70: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
3d80: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a lumn_name()]..**
3d90: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 .** ^If the 2nd
3da0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
3db0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 ite3_exec() is a
3dc0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 NULL pointer, a
3dd0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 pointer.** to a
3de0: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
3df0: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 or a pointer tha
3e00: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 t contains only
3e10: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f whitespace and/o
3e20: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e r .** SQL commen
3e30: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 ts, then no SQL
3e40: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 statements are e
3e50: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 valuated and the
3e60: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 database.** is
3e70: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a not changed..**.
3e80: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a ** Restrictions:
3e90: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
3ea0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
3eb0: 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 ion must insure
3ec0: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 that the 1st par
3ed0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3ee0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 3_exec().**
3ef0: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 is a valid and
3f00: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c onnection]..** <
3f20: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
3f30: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ion must not clo
3f40: 73 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e se [database con
3f50: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
3f60: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 ed by.** th
3f70: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
3f80: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
3f90: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f ) while sqlite3_
3fa0: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e exec() is runnin
3fb0: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 g..** <li> The a
3fc0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
3fd0: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 not modify the S
3fe0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
3ff0: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a t passed into.**
4000: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 the 2nd pa
4010: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 rameter of sqlit
4020: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 e3_exec() while
4030: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
4040: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f s running..** </
4050: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ul>.*/.SQLITE_AP
4060: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 I int sqlite3_ex
4070: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ec(. 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: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 /* An open data
40b0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 base */. const
40c0: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 char *sql,
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40e0: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
40f0: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
4100: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 int (*callback)
4110: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
4120: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 *,char**), /* C
4130: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
4140: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 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: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 /* 1st argument
4180: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a to callback */.
4190: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 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 20 2f 2a 20 /*
41c0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
41d0: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a n here */.);../*
41e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
41f0: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 sult Codes.** KE
4200: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f YWORDS: SQLITE_O
4210: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b K {error code} {
4220: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 error codes}.**
4230: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c KEYWORDS: {resul
4240: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 t code} {result
4250: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e codes}.**.** Man
4260: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f y SQLite functio
4270: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 ns return an int
4280: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 eger result code
4290: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 from the set sh
42a0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f own.** here in o
42b0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 rder to indicate
42c0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
42d0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
42e0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
42f0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
4300: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
4310: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
4320: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
4330: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
4340: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4350: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 ],.** [sqlite3_v
4360: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 tab_on_conflict(
4370: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 )] [SQLITE_ROLLB
4380: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 ACK | result cod
4390: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 es]..*/.#define
43a0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
43b0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
43c0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
43d0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d /* beginning-of-
43e0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 error-codes */.#
43f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 define SQLITE_ER
4400: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f ROR 1 /
4410: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d * SQL error or m
4420: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 issing database
4430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4440: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 E_INTERNAL 2
4450: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c /* Internal l
4460: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
4470: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
4480: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
4490: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
44a0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
44b0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
44c0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
44d0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
44e0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
44f0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
4500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4510: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
4520: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
4530: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4550: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
4560: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
4570: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
4580: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
4590: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
45a0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
45b0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
45c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
45d0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
45e0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
45f0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
4600: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
4620: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
4630: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
4640: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
4650: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
4660: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4670: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
4680: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
4690: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
46a0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
46b0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
46c0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
46d0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
46e0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
46f0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4700: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
4710: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 12 /* Unknown
4720: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 opcode in sqlite
4730: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4750: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 TE_FULL 1
4760: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 3 /* Insertion
4770: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 failed because
4780: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c database is full
4790: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
47a0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 TE_CANTOPEN 1
47b0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 4 /* Unable to
47c0: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
47d0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
47e0: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 ne SQLITE_PROTOC
47f0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 OL 15 /* Da
4800: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 tabase lock prot
4810: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 ocol error */.#d
4820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 efine SQLITE_EMP
4830: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a TY 16 /*
4840: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 Database is emp
4850: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ty */.#define SQ
4860: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 LITE_SCHEMA
4870: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 17 /* The dat
4880: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
4890: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nged */.#define
48a0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 SQLITE_TOOBIG
48b0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 18 /* Strin
48c0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 g or BLOB exceed
48d0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a s size limit */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
48f0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 ONSTRAINT 19
4900: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 /* Abort due to
4910: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
4920: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tion */.#define
4930: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 SQLITE_MISMATCH
4940: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 20 /* Data
4950: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f type mismatch */
4960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4970: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 MISUSE 21
4980: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 /* Library used
4990: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a incorrectly */.
49a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
49b0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 OLFS 22
49c0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 /* Uses OS featu
49d0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 res not supporte
49e0: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 d on host */.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
4a00: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
4a10: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 Authorization de
4a20: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
4a30: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 SQLITE_FORMAT
4a40: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 24 /* Auxil
4a50: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f iary database fo
4a60: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 rmat error */.#d
4a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e efine SQLITE_RAN
4a80: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a GE 25 /*
4a90: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
4aa0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f o sqlite3_bind o
4ab0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 ut of range */.#
4ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
4ad0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f TADB 26 /
4ae0: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 * File opened th
4af0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 at is not a data
4b00: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
4b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
4b20: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 CE 27 /*
4b30: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 Notifications fr
4b40: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 om sqlite3_log()
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4b60: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 TE_WARNING 2
4b70: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 8 /* Warnings
4b80: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 from sqlite3_log
4b90: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
4ba0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 LITE_ROW
4bb0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 100 /* sqlite3
4bc0: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 _step() has anot
4bd0: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f her row ready */
4be0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4bf0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 DONE 101
4c00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
4c10: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
4c20: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 executing */./*
4c30: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 end-of-error-cod
4c40: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 es */../*.** CAP
4c50: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 I3REF: Extended
4c60: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
4c70: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
4c80: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 ded error code}
4c90: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 {extended error
4ca0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 codes}.** KEYWOR
4cb0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
4cc0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 sult code} {exte
4cd0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4ce0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 s}.**.** In its
4cf0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
4d00: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 ation, SQLite AP
4d10: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 I routines retur
4d20: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 n one of 26 inte
4d30: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ger.** [SQLITE_O
4d40: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
4d50: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 ]. However, exp
4d60: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 erience has show
4d70: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a n that many of.*
4d80: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 * these result c
4d90: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 odes are too coa
4da0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 rse-grained. Th
4db0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 ey do not provid
4dc0: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 e as.** much inf
4dd0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 ormation about p
4de0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 roblems as progr
4df0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b ammers might lik
4e00: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 e. In an effort
4e10: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 to.** address t
4e20: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 his, newer versi
4e30: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 ons of SQLite (v
4e40: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 ersion 3.3.8 and
4e50: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a later) include.
4e60: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 ** support for a
4e70: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 dditional result
4e80: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 codes that prov
4e90: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 ide more detaile
4ea0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a d information.**
4eb0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 about errors. T
4ec0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
4ed0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
4ee0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
4ef0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 .** on a per dat
4f00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4f10: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 basis using the
4f20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
4f30: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
4f40: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a es()] API..**.**
4f50: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 Some of the ava
4f60: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 ilable extended
4f70: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4f80: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a listed here..**
4f90: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 One may expect
4fa0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
4fb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4fc0: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 des will be expa
4fd0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e nd.** over time.
4fe0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
4ff0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 uses extended re
5000: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c sult codes shoul
5010: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 d expect.** to s
5020: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f ee new result co
5030: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 des in future re
5040: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
5050: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
5060: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
5070: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
5080: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
5090: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
50a0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f exactly zero..*/
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
50c0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 IOERR_READ
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a IOERR | (1<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5100: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 OERR | (2<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5140: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 ERR_WRITE
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5160: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 ERR | (3<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5180: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 RR_FSYNC
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
51a0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 RR | (4<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
51c0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 R_DIR_FSYNC
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
51e0: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 R | (5<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5200: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 _TRUNCATE
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5220: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5240: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 FSTAT
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5260: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (7<<8)).#defin
5270: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 e SQLITE_IOERR_U
5280: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 NLOCK
5290: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
52a0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 SQLITE_IOERR_RD
52c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52e0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (9<<8)).#define
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c SQLITE_IOERR_DEL
5300: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 ETE (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5320: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 10<<8)).#define
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
5340: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 CKED (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5360: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 11<<8)).#define
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d SQLITE_IOERR_NOM
5380: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 EM (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
53a0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 12<<8)).#define
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
53c0: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 ESS (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
53e0: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 13<<8)).#define
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 SQLITE_IOERR_CHE
5400: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 CKRESERVEDLOCK (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5420: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 14<<8)).#define
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 SQLITE_IOERR_LOC
5440: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5460: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 15<<8)).#define
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f SQLITE_IOERR_CLO
5480: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 SE (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
54a0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 16<<8)).#define
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
54c0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 _CLOSE (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
54e0: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 17<<8)).#define
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
5500: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 OPEN (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5520: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 18<<8)).#define
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
5540: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 SIZE (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5560: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 19<<8)).#define
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
5580: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 LOCK (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
55a0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 20<<8)).#define
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
55c0: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 MAP (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
55e0: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 21<<8)).#define
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 SQLITE_IOERR_SEE
5600: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5620: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 22<<8)).#define
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c SQLITE_IOERR_DEL
5640: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 ETE_NOENT (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5660: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 23<<8)).#define
5670: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 SQLITE_IOERR_MMA
5680: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 P (
5690: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
56a0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 24<<8)).#define
56b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 SQLITE_LOCKED_SH
56c0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 AREDCACHE (
56d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 SQLITE_LOCKED |
56e0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
56f0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 SQLITE_BUSY_REC
5700: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 OVERY
5710: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c (SQLITE_BUSY |
5720: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
5740: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 N_NOTEMPDIR
5750: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
5760: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 N | (1<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
5780: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 PEN_ISDIR
5790: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
57a0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 PEN | (2<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
57c0: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 TOPEN_FULLPATH
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
57e0: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a TOPEN | (3<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5800: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 ORRUPT_VTAB
5810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5820: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 ORRUPT | (1<<8))
5830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5840: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 READONLY_RECOVER
5850: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f Y (SQLITE_
5860: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 READONLY | (1<<8
5870: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5880: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c E_READONLY_CANTL
5890: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 OCK (SQLIT
58a0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c E_READONLY | (2<
58b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
58c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c ITE_READONLY_ROL
58d0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c LBACK (SQL
58e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
58f0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
5900: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c QLITE_ABORT_ROLL
5910: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 BACK (S
5920: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 QLITE_ABORT | (2
5930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5950: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 CHECK (SQ
5960: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5970: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5980: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5990: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 INT_COMMITHOOK
59a0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
59b0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 INT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b STRAINT_FOREIGNK
59e0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e EY (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 STRAINT | (3<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 _CONSTRAINT_FUNC
5a20: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 TION (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 _CONSTRAINT | (4
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5a60: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 NOTNULL (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5a80: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 INT_PRIMARYKEY
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 INT | (6<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 STRAINT_TRIGGER
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 STRAINT | (7<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 _CONSTRAINT_UNIQ
5b30: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 UE (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 _CONSTRAINT | (8
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5b70: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 VTAB (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5b90: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (9<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f e SQLITE_NOTICE_
5bb0: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 RECOVER_WAL
5bc0: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 (SQLITE_NOTICE
5bd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f e SQLITE_NOTICE_
5bf0: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b RECOVER_ROLLBACK
5c00: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 (SQLITE_NOTICE
5c10: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a | (2<<8))../*.**
5c20: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
5c30: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
5c40: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 perations.**.**
5c50: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 These bit values
5c60: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
5c70: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 r use in the.**
5c80: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
5c90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 the [sqlite3_op
5ca0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
5cb0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 ce and.** in the
5cc0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
5cd0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
5ce0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
5cf0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5d00: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
5d10: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 Y 0x0000
5d20: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0001 /* Ok for
5d30: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5d40: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5d50: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
5d60: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 TE 0x0000
5d70: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0002 /* Ok for
5d80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5d90: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5da0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 ITE_OPEN_CREATE
5db0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5dc0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0004 /* Ok for
5dd0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5de0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5df0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
5e00: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 NCLOSE 0x0000
5e10: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0008 /* VFS onl
5e20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5e30: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
5e40: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 VE 0x0000
5e50: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0010 /* VFS onl
5e60: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5e70: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f ITE_OPEN_AUTOPRO
5e80: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 XY 0x0000
5e90: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0020 /* VFS onl
5ea0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5eb0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 ITE_OPEN_URI
5ec0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5ed0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0040 /* Ok for
5ee0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5ef0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5f00: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 ITE_OPEN_MEMORY
5f10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5f20: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0080 /* Ok for
5f30: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5f40: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5f50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
5f60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5f70: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0100 /* VFS onl
5f80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5f90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
5fa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5fb0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0200 /* VFS onl
5fc0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5fd0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
5fe0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 NT_DB 0x0000
5ff0: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0400 /* VFS onl
6000: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
6020: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
6030: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0800 /* VFS onl
6040: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
6050: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
6060: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
6070: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 1000 /* VFS onl
6080: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
6090: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
60a0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 NAL 0x0000
60b0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 2000 /* VFS onl
60c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
60d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
60e0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 JOURNAL 0x0000
60f0: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 4000 /* VFS onl
6100: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
6110: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
6120: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6130: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 8000 /* Ok for
6140: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
6150: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
6160: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
6170: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 EX 0x0001
6180: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
6190: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
61a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
61b0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
61c0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 ACHE 0x0002
61d0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
61e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
61f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
6200: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
6210: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 CACHE 0x0004
6220: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
6230: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
6240: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
6250: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 ITE_OPEN_WAL
6260: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 0x0008
6270: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0000 /* VFS onl
6280: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 y */../* Reserve
6290: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 d:
62a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 0x00F
62b0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 00000 */../*.**
62c0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
62d0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
62e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
62f0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
6300: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
6310: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
6320: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
6330: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
6340: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
6350: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 tor of these.**
6360: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
6370: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
6380: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
6390: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
63a0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
63b0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
63c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
63d0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
63e0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
63f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6400: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
6410: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
6420: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
6430: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
6440: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6450: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
6460: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
6470: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
6480: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
6490: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
64a0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
64b0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
64c0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
64d0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
64e0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
64f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6500: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
6510: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
6520: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
6530: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
6540: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
6550: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
6560: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
6570: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
6580: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
6590: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
65a0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
65b0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
65c0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
65d0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
65e0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
65f0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
6600: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
6610: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
6620: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 e(). The SQLITE
6630: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
6640: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 _OVERWRITE prope
6650: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
6660: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 * after reboot f
6670: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 ollowing a crash
6680: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 or power loss,
6690: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 the only bytes i
66a0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 n a.** file that
66b0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 were written at
66c0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
66d0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 level might hav
66e0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 e changed.** and
66f0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 that adjacent b
6700: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 ytes, even bytes
6710: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
6720: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 sector are.** g
6730: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 uaranteed to be
6740: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 unchanged..*/.#d
6750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6760: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 AP_ATOMIC
6770: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6780: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0001.#define SQL
6790: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
67a0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 512
67b0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 0x00000002.#def
67c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
67d0: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 _ATOMIC1K
67e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
67f0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 04.#define SQLIT
6800: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b E_IOCAP_ATOMIC2K
6810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6820: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
6830: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6840: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 TOMIC4K
6850: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
6860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6870: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 IOCAP_ATOMIC8K
6880: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6890: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 0000020.#define
68a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
68b0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 MIC16K
68c0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 0x00000040.#
68d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
68e0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 CAP_ATOMIC32K
68f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6900: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 00080.#define SQ
6910: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6920: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 C64K
6930: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 0x00000100.#de
6940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6950: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 P_SAFE_APPEND
6960: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6970: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 200.#define SQLI
6980: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
6990: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 IAL
69a0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 0x00000400.#defi
69b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
69c0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e UNDELETABLE_WHEN
69d0: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 _OPEN 0x0000080
69e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
69f0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
6a00: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 _OVERWRITE 0x
6a10: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 00001000../*.**
6a20: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
6a30: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a ocking Levels.**
6a40: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
6a50: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 one of these int
6a60: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
6a70: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 he second.** arg
6a80: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 ument to calls i
6a90: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 t makes to the x
6aa0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f Lock() and xUnlo
6ab0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 ck() methods.**
6ac0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 of an [sqlite3_i
6ad0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
6ae0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t..*/.#define SQ
6af0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 LITE_LOCK_NONE
6b00: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
6b10: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 e SQLITE_LOCK_SH
6b20: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 ARED 1.#d
6b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6b40: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 K_RESERVED
6b50: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
6b60: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 _LOCK_PENDING
6b70: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
6b80: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
6b90: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a IVE 4../*.**
6ba0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 CAPI3REF: Synch
6bb0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 ronization Type
6bc0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e Flags.**.** When
6bd0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
6be0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 the xSync() meth
6bf0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c od of an.** [sql
6c00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6c10: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 object it uses
6c20: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 a combination of
6c30: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 .** these intege
6c40: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
6c50: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
6c60: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
6c70: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
6c80: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 ONLY flag is use
6c90: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 d, it means that
6ca0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 the.** sync ope
6cb0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 ration only need
6cc0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 s to flush data
6cd0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e to mass storage.
6ce0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 Inode.** infor
6cf0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 mation need not
6d00: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 be flushed. If t
6d10: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
6d20: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a ts of the flag.*
6d30: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 * equal SQLITE_S
6d40: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 YNC_NORMAL, that
6d50: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f means to use no
6d60: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d rmal fsync() sem
6d70: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 antics..** If th
6d80: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
6d90: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 s equal SQLITE_S
6da0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d YNC_FULL, that m
6db0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d eans.** to use M
6dc0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
6dd0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f llsync instead o
6de0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a f fsync()..**.**
6df0: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 Do not confuse
6e00: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f the SQLITE_SYNC_
6e10: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
6e20: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 E_SYNC_FULL flag
6e30: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 s.** with the [P
6e40: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
6e50: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 s]=NORMAL and [P
6e60: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
6e70: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 s]=FULL.** setti
6e80: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 ngs. The [synch
6e90: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 ronous pragma] d
6ea0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 etermines when c
6eb0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 alls to the.** x
6ec0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 Sync VFS method
6ed0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 occur and applie
6ee0: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f s uniformly acro
6ef0: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 ss all platforms
6f00: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
6f10: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
6f20: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
6f30: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 flags determine
6f40: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 how.** energeti
6f50: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 c or rigorous or
6f60: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 forceful the sy
6f70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 nc operations ar
6f80: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 e and.** only ma
6f90: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 ke a difference
6fa0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 on Mac OSX for t
6fb0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 he default SQLit
6fc0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 e code..** (Thir
6fd0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c d-party VFS impl
6fe0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 ementations migh
6ff0: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 t also make the
7000: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
7010: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 etween SQLITE_SY
7020: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
7030: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 LITE_SYNC_FULL,
7040: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a but among the.**
7050: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
7060: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 ms natively supp
7070: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c orted by SQLite,
7080: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a only Mac OSX.**
7090: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 cares about the
70a0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f difference.).*/
70b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
70c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 SYNC_NORMAL
70d0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 0x00002.#defi
70e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 ne SQLITE_SYNC_F
70f0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 ULL 0x0
7100: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 0003.#define SQL
7110: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
7120: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a Y 0x00010..
7130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7140: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 OS Interface Ope
7150: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a n File Handle.**
7160: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
7170: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
7180: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
7190: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 file in the .**
71a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f [sqlite3_vfs | O
71b0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
71c0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 r]. Individual
71d0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 OS interface.**
71e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
71f0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 will.** want to
7200: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 subclass this ob
7210: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e ject by appendin
7220: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 g additional fie
7230: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 lds.** for their
7240: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 own use. The p
7250: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 Methods entry is
7260: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
7270: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
7280: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
7290: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 that defines met
72a0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d hods for perform
72b0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 ing.** I/O opera
72c0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 tions on the ope
72d0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 n file..*/.typed
72e0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
72f0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 3_file sqlite3_f
7300: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ile;.struct sqli
7310: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e te3_file {. con
7320: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 st struct sqlite
7330: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 3_io_methods *pM
7340: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 ethods; /* Meth
7350: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 ods for an open
7360: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a file */.};../*.*
7370: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
7380: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 nterface File Vi
7390: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 rtual Methods Ob
73a0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 ject.**.** Every
73b0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 file opened by
73c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
73d0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 .xOpen] method p
73e0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b opulates an.** [
73f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
7400: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 ject (or, more c
7410: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c ommonly, a subcl
7420: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ass of the.** [s
7430: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
7440: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e ect) with a poin
7450: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
7460: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
7470: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
7480: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 t defines the me
7490: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 thods used to pe
74a0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 rform various op
74b0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 erations.** agai
74c0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c nst the open fil
74d0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 e represented by
74e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
74f0: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a le] object..**.*
7500: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * If the [sqlite
7510: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7520: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c hod sets the sql
7530: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
7540: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 ds element .** t
7550: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 o a non-NULL poi
7560: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 nter, then the s
7570: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7580: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a s.xClose method.
7590: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ** may be invoke
75a0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 d even if the [s
75b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
75c0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 ] reported that
75d0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a it failed. The.
75e0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 ** only way to p
75f0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f revent a call to
7600: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e xClose followin
7610: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 g a failed [sqli
7620: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a te3_vfs.xOpen].*
7630: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 * is for the [sq
7640: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7650: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 to set the sqli
7660: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
7670: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 s element.** to
7680: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
7690: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
76a0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
76b0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
76c0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
76d0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
76e0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
76f0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
7700: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
7710: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
7720: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 ce is a Mac OS X
7730: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
7740: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
7750: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
7760: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
7770: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
7780: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
7790: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
77a0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
77b0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
77c0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
77d0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
77e0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
77f0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
7800: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
7810: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
7820: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
7830: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
7840: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
7850: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
7860: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
7880: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
7890: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
78a0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
78b0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
78c0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
78d0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
78e0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
78f0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
7900: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
7910: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
7920: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
7930: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
7940: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
7950: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
7960: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
7970: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
7980: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
7990: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
79a0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
79b0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
79c0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
79d0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
79e0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
79f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
7a00: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
7a10: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
7a20: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
7a30: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
7a40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7a50: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
7a60: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
7a70: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
7a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
7a90: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
7aa0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
7ab0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
7ac0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
7ad0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
7ae0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
7af0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
7b00: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
7b10: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
7b20: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
7b30: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
7b40: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
7b50: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
7b60: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
7b70: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
7b80: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
7b90: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
7ba0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
7bb0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
7bc0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
7bd0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
7be0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
7bf0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
7c00: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
7c10: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
7c20: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
7c30: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
7c40: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
7c50: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
7c60: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
7c70: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
7c80: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
7c90: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
7ca0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c A [SQLITE_FCNTL
7cb0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 _LOCKSTATE | lis
7cc0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 t of opcodes] le
7cd0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 ss than 100 is a
7ce0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 vailable..** App
7cf0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 lications that d
7d00: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 efine a custom x
7d10: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
7d20: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 od should use op
7d30: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 codes.** greater
7d40: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f than 100 to avo
7d50: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 id conflicts. V
7d60: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
7d70: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ns should.** ret
7d80: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 urn [SQLITE_NOTF
7d90: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 OUND] for file c
7da0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 ontrol opcodes t
7db0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
7dc0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a ** recognize..**
7dd0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 .** The xSectorS
7de0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 ize() method ret
7df0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 urns the sector
7e00: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 size of the.** d
7e10: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 evice that under
7e20: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 lies the file.
7e30: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 The sector size
7e40: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 is the.** minimu
7e50: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e m write that can
7e60: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 be performed wi
7e70: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 thout disturbing
7e80: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 .** other bytes
7e90: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 in the file. Th
7ea0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
7eb0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 eristics().** me
7ec0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 thod returns a b
7ed0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 it vector descri
7ee0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f bing behaviors o
7ef0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
7f00: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a ing device:.**.*
7f10: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
7f20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7f30: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 MIC].** <li> [SQ
7f40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7f50: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C512].** <li> [S
7f60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7f70: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC1K].** <li> [S
7f80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7f90: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC2K].** <li> [S
7fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7fb0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC4K].** <li> [S
7fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7fd0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC8K].** <li> [S
7fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7ff0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC16K].** <li> [
8000: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8010: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC32K].** <li>
8020: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8030: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC64K].** <li>
8040: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
8050: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c AFE_APPEND].** <
8060: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
8070: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a P_SEQUENTIAL].**
8080: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
8090: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
80a0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
80b0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
80c0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
80d0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
80e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
80f0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
8100: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
8110: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
8120: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
8130: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
8140: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
8150: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
8160: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
8170: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
8180: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
8190: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
81a0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
81b0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
81c0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
81d0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
81e0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
81f0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
8200: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
8210: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
8220: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
8230: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
8240: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
8250: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
8260: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
8270: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
8280: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
8290: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
82a0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
82b0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
82c0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 ()..**.** If xRe
82d0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c ad() returns SQL
82e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
82f0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 READ it must als
8300: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 o fill.** in the
8310: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 unread portions
8320: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 of the buffer w
8330: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 ith zeros. A VF
8340: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 S that.** fails
8350: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
8360: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 rt reads might s
8370: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f eem to work. Ho
8380: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 wever,.** failur
8390: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 e to zero-fill s
83a0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 hort reads will
83b0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 eventually lead
83c0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 to.** database c
83d0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 orruption..*/.ty
83e0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
83f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
8400: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8410: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
8420: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a e3_io_methods {.
8430: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a int iVersion;.
8440: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
8450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
8460: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 int (*xRead)(s
8470: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f qlite3_file*, vo
8480: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
8490: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
84a0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 st);. int (*xWr
84b0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ite)(sqlite3_fil
84c0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c e*, const void*,
84d0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
84e0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
84f0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 . int (*xTrunca
8500: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
8510: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8520: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a size);. int (*
8530: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 xSync)(sqlite3_f
8540: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 ile*, int flags)
8550: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 ;. int (*xFileS
8560: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
8570: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
8580: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 4 *pSize);. int
8590: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 (*xLock)(sqlite
85a0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
85b0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 int (*xUnlock)(
85c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
85d0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 nt);. int (*xCh
85e0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 eckReservedLock)
85f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8600: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
8610: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 int (*xFileCont
8620: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c rol)(sqlite3_fil
8630: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 e*, int op, void
8640: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *pArg);. int (
8650: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 *xSectorSize)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
8670: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 int (*xDeviceCha
8680: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 racteristics)(sq
8690: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
86a0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
86b0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
86c0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e ersion 1 */. in
86d0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c t (*xShmMap)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
86f0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 iPg, int pgsz, i
8700: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c nt, void volatil
8710: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 e**);. int (*xS
8720: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f hmLock)(sqlite3_
8730: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 file*, int offse
8740: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c t, int n, int fl
8750: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ags);. void (*x
8760: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 ShmBarrier)(sqli
8770: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
8780: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 t (*xShmUnmap)(s
8790: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
87a0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 t deleteFlag);.
87b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
87c0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
87d0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 version 2 */. i
87e0: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c nt (*xFetch)(sql
87f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
8800: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c te3_int64 iOfst,
8810: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 int iAmt, void
8820: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 **pp);. int (*x
8830: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 Unfetch)(sqlite3
8840: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
8850: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 int64 iOfst, voi
8860: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 d *p);. /* Meth
8870: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
8880: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
8890: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 3 */. /* Additi
88a0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 onal methods may
88b0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
88c0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a ure releases */.
88d0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
88e0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c EF: Standard Fil
88f0: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 e Control Opcode
8900: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e s.**.** These in
8910: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
8920: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 are opcodes for
8930: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
8940: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 method.** of th
8950: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
8960: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e thods] object an
8970: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 d for the [sqlit
8980: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
8990: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e )].** interface.
89a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
89b0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
89c0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
89d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
89e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
89f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
8a00: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
8a10: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 to write the cu
8a20: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a rrent state of.*
8a30: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 * the lock (one
8a40: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f of [SQLITE_LOCK_
8a50: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c NONE], [SQLITE_L
8a60: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
8a70: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
8a80: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f ERVED], [SQLITE_
8a90: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
8aa0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 r [SQLITE_LOCK_E
8ab0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e XCLUSIVE]).** in
8ac0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 to an integer th
8ad0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 at the pArg argu
8ae0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 ment points to.
8af0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a This capability.
8b00: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ** is used durin
8b10: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e g testing and on
8b20: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 ly needs to be s
8b30: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 upported when SQ
8b40: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 LITE_TEST.** is
8b50: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e defined..** <ul>
8b60: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
8b70: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
8b80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
8b90: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
8ba0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 T] opcode is use
8bb0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 d by SQLite to g
8bc0: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c ive the VFS.** l
8bd0: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 ayer a hint of h
8be0: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 ow large the dat
8bf0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
8c00: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e grow to be durin
8c10: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 g the.** current
8c20: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 transaction. T
8c30: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 his hint is not
8c40: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 guaranteed to be
8c50: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 accurate but it
8c60: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f .** is often clo
8c70: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 se. The underly
8c80: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 ing VFS might ch
8c90: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 oose to prealloc
8ca0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ate database.**
8cb0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 file space based
8cc0: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e on this hint in
8cd0: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 order to help w
8ce0: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 rites to the dat
8cf0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 abase.** file ru
8d00: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 n faster..**.**
8d10: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
8d20: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a TL_CHUNK_SIZE]].
8d30: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
8d40: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d CNTL_CHUNK_SIZE]
8d50: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
8d60: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 to request that
8d70: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e the VFS.** exten
8d80: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 ds and truncates
8d90: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
8da0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 le in chunks of
8db0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 a size specified
8dc0: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e .** by the user.
8dd0: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 The fourth argu
8de0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
8df0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
8e00: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e should .** poin
8e10: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 t to an integer
8e20: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 (type int) conta
8e30: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 ining the new ch
8e40: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a unk-size to use.
8e50: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e ** for the nomin
8e60: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 ated database. A
8e70: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 llocating databa
8e80: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e se file space in
8e90: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 large.** chunks
8ea0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 (say 1MB at a t
8eb0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 ime), may reduce
8ec0: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 file-system fra
8ed0: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a gmentation and.*
8ee0: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 * improve perfor
8ef0: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 mance on some sy
8f00: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 stems..**.** <li
8f10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
8f20: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a FILE_POINTER]].*
8f30: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
8f40: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
8f50: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
8f60: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 to obtain a poi
8f70: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
8f80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
8f90: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 ject associated
8fa0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
8fb0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f r database.** co
8fc0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 nnection. See t
8fd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
8fe0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 _control()] docu
8ff0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
9000: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
9010: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c rmation..**.** <
9020: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
9030: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d L_SYNC_OMITTED]]
9040: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
9050: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
9060: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 TTED] opcode is
9070: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e generated intern
9080: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 ally by.** SQLit
9090: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c e and sent to al
90a0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 l VFSes in place
90b0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 of a call to th
90c0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a e xSync method.*
90d0: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 * when the datab
90e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 ase connection h
90f0: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 as [PRAGMA synch
9100: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f ronous] set to O
9110: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 FF.)^.** Some sp
9120: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
9130: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c need this signal
9140: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 in order to ope
9150: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a rate correctly.*
9160: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 * when [PRAGMA s
9170: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 ynchronous | PRA
9180: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d GMA synchronous=
9190: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 OFF] is set, but
91a0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 most .** VFSes
91b0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 do not need this
91c0: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 signal and shou
91d0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
91e0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a re this opcode..
91f0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
9200: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 should not call
9210: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
9220: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
9230: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 is.** opcode as
9240: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 doing so may dis
9250: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 rupt the operati
9260: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 on of the specia
9270: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 lized VFSes.** t
9280: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 hat do require i
9290: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b t. .**.** <li>[
92a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 [SQLITE_FCNTL_WI
92b0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a N32_AV_RETRY]].*
92c0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
92d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
92e0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TRY] opcode is u
92f0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 sed to configure
9300: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 automatic.** re
9310: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 try counts and i
9320: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 ntervals for cer
9330: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 tain disk I/O op
9340: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 erations for the
9350: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 .** windows [VFS
9360: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 ] in order to pr
9370: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 ovide robustness
9380: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 in the presence
9390: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 of.** anti-viru
93a0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 s programs. By
93b0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e default, the win
93c0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 dows VFS will re
93d0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a try file read,.*
93e0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e * file write, an
93f0: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 d file delete op
9400: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 erations up to 1
9410: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 0 times, with a
9420: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d delay.** of 25 m
9430: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f illiseconds befo
9440: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 re the first ret
9450: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 ry and with the
9460: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 delay increasing
9470: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 .** by an additi
9480: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 onal 25 millisec
9490: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 onds with each s
94a0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e ubsequent retry.
94b0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
94c0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 allows these tw
94d0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 o values (10 ret
94e0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c ries and 25 mill
94f0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 iseconds of dela
9500: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 y).** to be adju
9510: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 sted. The value
9520: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f s are changed fo
9530: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 r all database c
9540: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 onnections.** wi
9550: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 thin the same pr
9560: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 ocess. The argu
9570: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
9580: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 r to an array of
9590: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 two.** integers
95a0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 where the first
95b0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e integer i the n
95c0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 ew retry count a
95d0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a nd the second.**
95e0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 integer is the
95f0: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 delay. If eithe
9600: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 r integer is neg
9610: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
9620: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f setting.** is no
9630: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e t changed but in
9640: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 stead the prior
9650: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 value of that se
9660: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e tting is written
9670: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 .** into the arr
9680: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 ay entry, allowi
9690: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 ng the current r
96a0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f etry settings to
96b0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 be.** interroga
96c0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d ted. The zDbNam
96d0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 e parameter is i
96e0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c gnored..**.** <l
96f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9700: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a _PERSIST_WAL]].*
9710: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
9720: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
9730: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
9740: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 to set or query
9750: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 the.** persiste
9760: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 nt [WAL | Write
9770: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 Ahead Log] setti
9780: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ng. By default,
9790: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a the auxiliary.*
97a0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f * write ahead lo
97b0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d g and shared mem
97c0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 ory files used f
97d0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 or transaction c
97e0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 ontrol.** are au
97f0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
9800: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 ted when the lat
9810: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 est connection t
9820: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
9830: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 * closes. Setti
9840: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 ng persistent WA
9850: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 L mode causes th
9860: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 ose files to per
9870: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c sist after.** cl
9880: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 ose. Persisting
9890: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 the files is us
98a0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 eful when other
98b0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 processes that d
98c0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 o not.** have wr
98d0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f ite permission o
98e0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 n the directory
98f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 containing the d
9900: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e atabase file wan
9910: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 t.** to read the
9920: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
9930: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 as the WAL and s
9940: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
9950: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a es must exist.**
9960: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 in order for th
9970: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 e database to be
9980: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
9990: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
99a0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
99b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
99c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
99d0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
99e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
99f0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
9a00: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
9a10: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 le persistent WA
9a20: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 L mode or 1 to e
9a30: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 nable persistent
9a40: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 .** WAL mode. I
9a50: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
9a60: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
9a70: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
9a80: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
9a90: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 WAL persistence
9aa0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c setting..**.** <
9ab0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
9ac0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
9ad0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
9ae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f [SQLITE_FCNTL_PO
9af0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
9b00: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
9b10: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
9b20: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
9b30: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f ent "powersafe-o
9b40: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 verwrite" or "PS
9b50: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 OW" setting. Th
9b60: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a e PSOW setting.*
9b70: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 * determines the
9b80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 [SQLITE_IOCAP_P
9b90: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
9ba0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a TE] bit of the.*
9bb0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 * xDeviceCharact
9bc0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 eristics methods
9bd0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 . The fourth par
9be0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
9bf0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
9c00: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f ol()] for this o
9c10: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 pcode should be
9c20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
9c30: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 integer..** That
9c40: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f integer is 0 to
9c50: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 disable zero-da
9c60: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 mage mode or 1 t
9c70: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 o enable zero-da
9c80: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 mage.** mode. I
9c90: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
9ca0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
9cb0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
9cc0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
9cd0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
9ce0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
9cf0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9d00: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a TL_OVERWRITE]].*
9d10: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
9d20: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 CNTL_OVERWRITE]
9d30: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 opcode is invoke
9d40: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 d by SQLite afte
9d50: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 r opening.** a w
9d60: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
9d70: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
9d80: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 t, unless it is
9d90: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 rolled back for
9da0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 some.** reason,
9db0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 the entire datab
9dc0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 ase file will be
9dd0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
9de0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
9df0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
9e00: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 s is used by VAC
9e10: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a UUM operations..
9e20: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9e30: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
9e40: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
9e50: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
9e60: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 ] opcode can be
9e70: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 used to obtain t
9e80: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 he names of.** a
9e90: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 ll [VFSes] in th
9ea0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 e VFS stack. Th
9eb0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 e names are of a
9ec0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 ll VFS shims and
9ed0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f the.** final bo
9ee0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 ttom-level VFS a
9ef0: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 re written into
9f00: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
9f10: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
9f20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
9f30: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 the result is st
9f40: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 ored in the char
9f50: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 * variable.** th
9f60: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 at the fourth pa
9f70: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 rameter of [sqli
9f80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
9f90: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a ()] points to..*
9fa0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 * The caller is
9fb0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
9fc0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f freeing the memo
9fd0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 ry when done. A
9fe0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 s with.** all fi
9ff0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f le-control actio
a000: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 ns, there is no
a010: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
a020: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c his will actuall
a030: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 y.** do anything
a040: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c . Callers shoul
a050: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 d initialize the
a060: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 char* variable
a070: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 to a NULL.** poi
a080: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 nter in case thi
a090: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
a0a0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 s not implemente
a0b0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f d. This file-co
a0c0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 ntrol.** is inte
a0d0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 nded for diagnos
a0e0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a tic use only..**
a0f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
a100: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a _FCNTL_PRAGMA]].
a110: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b ** ^Whenever a [
a120: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e PRAGMA] statemen
a130: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 t is parsed, an
a140: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
a150: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 AGMA] .** file c
a160: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 ontrol is sent t
a170: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 o the open [sqli
a180: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
a190: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
a1a0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 * to the databas
a1b0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 e file to which
a1c0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 the pragma state
a1d0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 ment refers. ^Th
a1e0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f e argument.** to
a1f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
a200: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
a210: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 control is an ar
a220: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 ray of.** pointe
a230: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 rs to strings (c
a240: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 har**) in which
a250: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 the second eleme
a260: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a nt of the array.
a270: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
a280: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 f the pragma and
a290: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 the third eleme
a2a0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 nt is the argume
a2b0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 nt to the.** pra
a2c0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 gma or NULL if t
a2d0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f he pragma has no
a2e0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 argument. ^The
a2f0: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a handler for an.
a300: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
a310: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
a320: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e ntrol can option
a330: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 ally make the fi
a340: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f rst element.** o
a350: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 f the char** arg
a360: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 ument point to a
a370: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
a380: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
a390: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 printf()].** or
a3a0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 the equivalent a
a3b0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 nd that string w
a3c0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 ill become the r
a3d0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 esult of the pra
a3e0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 gma or.** the er
a3f0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 ror message if t
a400: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e he pragma fails.
a410: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
a420: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a430: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 ] file control r
a440: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e eturns [SQLITE_N
a450: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e OTFOUND], then n
a460: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d ormal .** [PRAGM
a470: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f A] processing co
a480: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 ntinues. ^If th
a490: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a4a0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
a4b0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 control returns
a4c0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 [SQLITE_OK], the
a4d0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 n the parser ass
a4e0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
a4f0: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 VFS has handled
a500: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 the PRAGMA itse
a510: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 lf and the parse
a520: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f r generates a no
a530: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 -op.** prepared
a540: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 statement. ^If
a550: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
a560: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
a570: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a ontrol returns.*
a580: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 * any result cod
a590: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 e other than [SQ
a5a0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c LITE_OK] or [SQL
a5b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 ITE_NOTFOUND], t
a5c0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 hat means.** tha
a5d0: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e t the VFS encoun
a5e0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 tered an error w
a5f0: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 hile handling th
a600: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 e [PRAGMA] and t
a610: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f he.** compilatio
a620: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 n of the PRAGMA
a630: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 fails with an er
a640: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 ror. ^The [SQLI
a650: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
a660: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
a670: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 occurs at the b
a680: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 eginning of prag
a690: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 ma statement ana
a6a0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 lysis and so.**
a6b0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 it is able to ov
a6c0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 erride built-in
a6d0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 [PRAGMA] stateme
a6e0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nts..**.** <li>[
a6f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 [SQLITE_FCNTL_BU
a700: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e SYHANDLER]].** ^
a710: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
a720: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a L_BUSYHANDLER].*
a730: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d * file-control m
a740: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 ay be invoked by
a750: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 SQLite on the d
a760: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e atabase file han
a770: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 dle.** shortly a
a780: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 fter it is opene
a790: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 d in order to pr
a7a0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 ovide a custom V
a7b0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a FS with access.*
a7c0: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 * to the connect
a7d0: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 ions busy-handle
a7e0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 r callback. The
a7f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 argument is of t
a800: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a ype (void **).**
a810: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 - an array of t
a820: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 wo (void *) valu
a830: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 es. The first (v
a840: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 oid *) actually
a850: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 points.** to a f
a860: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 unction of type
a870: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 (int (*)(void *)
a880: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 ). In order to i
a890: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 nvoke the connec
a8a0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 tions.** busy-ha
a8b0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 ndler, this func
a8c0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 tion should be i
a8d0: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 nvoked with the
a8e0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 second (void *)
a8f0: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 in.** the array
a900: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 as the only argu
a910: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 ment. If it retu
a920: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
a930: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e en the operation
a940: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
a950: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 tried. If it ret
a960: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 urns zero, the c
a970: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 ustom VFS should
a980: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 abandon the.**
a990: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f current operatio
a9a0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 n..**.** <li>[[S
a9b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
a9c0: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 FILENAME]].** ^A
a9d0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 pplication can i
a9e0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 nvoke the [SQLIT
a9f0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
aa00: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 NAME] file-contr
aa10: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 ol.** to have SQ
aa20: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a Lite generate a.
aa30: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
aa40: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 ename using the
aa50: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 same algorithm t
aa60: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 hat is followed
aa70: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 to generate.** t
aa80: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d emporary filenam
aa90: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c es for TEMP tabl
aaa0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 es and other int
aab0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 ernal uses. The
aac0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f .** argument sho
aad0: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 uld be a char**
aae0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 which will be fi
aaf0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 lled with the fi
ab00: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 lename.** writte
ab10: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
ab20: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
ab30: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
ab40: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 The caller shou
ab50: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 ld.** invoke [sq
ab60: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e lite3_free()] on
ab70: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 the result to a
ab80: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 void a memory le
ab90: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ak..**.** <li>[[
aba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
abb0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 P_SIZE]].** The
abc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d [SQLITE_FCNTL_MM
abd0: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f AP_SIZE] file co
abe0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f ntrol is used to
abf0: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 query or set th
ac00: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d e.** maximum num
ac10: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 ber of bytes tha
ac20: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 t will be used f
ac30: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 or memory-mapped
ac40: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 I/O..** The arg
ac50: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
ac60: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 er to a value of
ac70: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e type sqlite3_in
ac80: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 t64 that.** is a
ac90: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d n advisory maxim
aca0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 um number of byt
acb0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 es in the file t
acc0: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 o memory map. T
acd0: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 he.** pointer is
ace0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
acf0: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e h the old value.
ad00: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e The limit is n
ad10: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a ot changed if.**
ad20: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 the value origi
ad30: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f nally pointed to
ad40: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e is negative, an
ad50: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 d so the current
ad60: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 limit .** can b
ad70: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 e queried by pas
ad80: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 sing in a pointe
ad90: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 r to a negative
ada0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a number. This.**
adb0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
adc0: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
add0: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 to implement [P
ade0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
adf0: 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f ..**.** </ul>.*/
ae00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ae10: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
ae20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 1.
ae30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
ae40: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
ae50: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
ae60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
ae70: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
ae80: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
ae90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 efine SQLITE_LAS
aea0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 T_ERRNO
aeb0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
aec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
aed0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 L_SIZE_HINT
aee0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
aef0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
af00: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 _CHUNK_SIZE
af10: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
af20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
af30: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 FILE_POINTER
af40: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
af50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
af60: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 YNC_OMITTED
af70: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
af80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
af90: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 N32_AV_RETRY
afa0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
afb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
afc0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 SIST_WAL
afd0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
afe0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
aff0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
b000: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 11.#define SQ
b010: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
b020: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ME
b030: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 12.#define SQL
b040: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
b050: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 AFE_OVERWRITE
b060: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 13.#define SQLI
b070: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 TE_FCNTL_PRAGMA
b080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b090: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 14.#define SQLIT
b0a0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
b0b0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 LER 1
b0c0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
b0d0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e _FCNTL_TEMPFILEN
b0e0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 AME 16
b0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b100: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 FCNTL_MMAP_SIZE
b110: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 18.
b120: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
b130: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
b140: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
b150: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
b160: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
b170: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
b180: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
b190: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
b1a0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
b1b0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
b1c0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
b1d0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
b1e0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
b1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
b200: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
b210: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
b220: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
b230: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
b240: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
b250: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
b260: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
b270: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
b280: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
b290: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
b2a0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
b2b0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
b2c0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ace Object.**.**
b2d0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
b2e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
b2f0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
b300: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
b310: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
b320: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
b330: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
b340: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
b350: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
b360: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
b370: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
b380: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
b390: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 stem". See.** t
b3a0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f he [VFS | VFS do
b3b0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
b3c0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 further informa
b3d0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
b3e0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
b3f0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
b400: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
b410: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
b420: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
b430: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
b440: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
b450: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
b460: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
b470: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
b480: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
b490: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
b4a0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
b4b0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
b4c0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
b4d0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
b4e0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
b4f0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
b500: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
b510: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
b520: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
b530: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
b540: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
b550: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
b560: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
b570: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
b580: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
b590: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
b5a0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
b5b0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
b5c0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
b5d0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
b5e0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
b5f0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
b600: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
b610: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
b620: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
b630: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
b640: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
b650: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
b660: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
b670: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
b680: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
b690: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
b6a0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
b6b0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
b6c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
b6d0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
b6e0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
b6f0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
b700: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
b710: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
b720: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
b730: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
b740: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
b750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
b760: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
b770: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
b780: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
b790: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
b7a0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
b7b0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
b7c0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
b7d0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
b7e0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
b7f0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
b800: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
b810: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
b820: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
b830: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
b840: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
b850: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
b860: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
b870: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
b880: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
b890: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
b8a0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
b8b0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
b8c0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
b8d0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
b8e0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
b8f0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 s..**.** [[sqlit
b900: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a e3_vfs.xOpen]].*
b910: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
b920: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
b930: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
b940: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
b950: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
b960: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
b970: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
b980: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
b990: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
b9a0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
b9b0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
b9c0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
b9d0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
b9e0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
b9f0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
ba00: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
ba10: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
ba20: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
ba30: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 1 alphanumeric a
ba40: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
ba50: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
ba60: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
ba70: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
ba80: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
ba90: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
baa0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
bab0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
bac0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
bad0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
bae0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
baf0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
bb00: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
bb10: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
bb20: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
bb30: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
bb40: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
bb50: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
bb60: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
bb70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
bb80: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
bb90: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
bba0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
bbb0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
bbc0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
bbd0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
bbe0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
bbf0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
bc00: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
bc10: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
bc20: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
bc30: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
bc40: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
bc50: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
bc60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
bc70: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
bc80: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
bc90: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
bca0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
bcb0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
bcc0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
bcd0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
bce0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
bcf0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
bd00: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
bd10: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
bd20: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
bd30: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
bd40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
bd50: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
bd60: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
bd70: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
bd80: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
bd90: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
bda0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
bdb0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
bdc0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
bdd0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
bde0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
bdf0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
be00: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
be10: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
be20: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
be30: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
be40: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
be50: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
be60: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
be70: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
be80: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
be90: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
bea0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
beb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
bec0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
bed0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
bee0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
bef0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
bf00: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
bf10: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
bf20: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
bf30: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
bf40: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
bf50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
bf60: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
bf70: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
bf80: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
bf90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
bfa0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
bfb0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
bfc0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
bfd0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
bfe0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
bff0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
c000: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
c010: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
c020: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
c030: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
c040: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
c050: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
c060: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
c070: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
c080: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
c090: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
c0a0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
c0b0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
c0c0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
c0d0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
c0e0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
c0f0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
c100: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
c110: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
c120: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
c130: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
c140: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
c150: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
c160: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
c170: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
c180: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
c190: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
c1a0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
c1b0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
c1c0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
c1d0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
c1e0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
c1f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
c200: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
c210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
c220: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
c230: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
c240: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
c250: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
c260: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
c270: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
c280: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
c290: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
c2a0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
c2b0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
c2c0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
c2d0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
c2e0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
c2f0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
c300: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
c310: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
c320: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
c330: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
c340: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
c350: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
c360: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
c370: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
c380: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
c390: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
c3a0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
c3b0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
c3c0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
c3d0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
c3e0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
c3f0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
c400: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
c410: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
c420: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
c430: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
c440: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
c450: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
c460: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
c470: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
c480: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
c490: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
c4a0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
c4b0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
c4c0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
c4d0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
c4e0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
c4f0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
c500: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
c510: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
c520: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
c530: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
c540: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
c550: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
c560: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
c570: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
c580: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
c590: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
c5a0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
c5b0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
c5c0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
c5d0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
c5e0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
c5f0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
c600: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
c610: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
c620: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
c630: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
c640: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
c650: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
c660: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
c670: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
c680: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
c690: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
c6a0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
c6b0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
c6c0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
c6d0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
c6e0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
c6f0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
c700: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
c710: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
c720: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c all..**.** [[sql
c730: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 ite3_vfs.xAccess
c740: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 ]].** ^The flags
c750: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
c760: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
c770: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
c780: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
c790: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
c7a0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
c7b0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
c7c0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
c7d0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
c7e0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
c7f0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
c800: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
c810: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
c820: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
c830: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
c840: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
c850: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
c860: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
c870: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
c880: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
c890: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
c8a0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
c8b0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
c8c0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
c8d0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
c8e0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
c8f0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
c900: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
c910: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
c920: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
c930: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
c940: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
c950: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
c960: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
c970: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
c980: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
c990: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
c9a0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
c9b0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
c9c0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
c9d0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
c9e0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
c9f0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
ca00: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
ca10: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
ca20: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
ca30: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
ca40: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
ca50: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
ca60: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
ca70: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
ca80: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
ca90: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
caa0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
cab0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
cac0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
cad0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
cae0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
caf0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
cb00: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
cb10: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
cb20: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
cb30: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
cb40: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
cb50: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
cb60: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
cb70: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
cb80: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
cb90: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
cba0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
cbb0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
cbc0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
cbd0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
cbe0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
cbf0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
cc00: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
cc10: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
cc20: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
cc30: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
cc40: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
cc50: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
cc60: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
cc70: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
cc80: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
cc90: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
cca0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
ccb0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
ccc0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 Number multipli
ccd0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 ed by 86400000 (
cce0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
ccf0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a lliseconds in .*
cd00: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 * a 24-hour day)
cd10: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 . .** ^SQLite w
cd20: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 ill use the xCur
cd30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
cd40: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 method to get th
cd50: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 e current.** dat
cd60: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 e and time if th
cd70: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 at method is ava
cd80: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 ilable (if iVers
cd90: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 ion is 2 or .**
cda0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 greater and the
cdb0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
cdc0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e is not NULL) an
cdd0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b d will fall back
cde0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 .** to xCurrentT
cdf0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e ime() if xCurren
ce00: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 tTimeInt64() is
ce10: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a unavailable..**.
ce20: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 ** ^The xSetSyst
ce30: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 emCall(), xGetSy
ce40: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 stemCall(), and
ce50: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 xNestSystemCall(
ce60: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
ce70: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 are not used by
ce80: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e the SQLite core.
ce90: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c These optional
cea0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
ceb0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 provided.** by s
cec0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 ome VFSes to fac
ced0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 ilitate testing
cee0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e of the VFS code.
cef0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a By overriding .
cf00: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 ** system calls
cf10: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 with functions u
cf20: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c nder its control
cf30: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d , a test program
cf40: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 can.** simulate
cf50: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f faults and erro
cf60: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 r conditions tha
cf70: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 t would otherwis
cf80: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a e be difficult.*
cf90: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 * or impossible
cfa0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 to induce. The
cfb0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 set of system ca
cfc0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 lls that can be
cfd0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 overridden.** va
cfe0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 ries from one VF
cff0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e S to another, an
d000: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 d from one versi
d010: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 on of the same V
d020: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 FS to the.** nex
d030: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
d040: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 that use these
d050: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 interfaces must
d060: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 be prepared for
d070: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 any.** or all of
d080: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
d090: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 s to be NULL or
d0a0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 for their behavi
d0b0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 or to change.**
d0c0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
d0d0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 to the next. A
d0e0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
d0f0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 not attempt to
d100: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 access.** any of
d110: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 these methods i
d120: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f f the iVersion o
d130: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 f the VFS is les
d140: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 s than 3..*/.typ
d150: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
d160: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
d170: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 vfs;.typedef voi
d180: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 d (*sqlite3_sysc
d190: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a all_ptr)(void);.
d1a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
d1b0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
d1c0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
d1d0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
d1e0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 sion number (cur
d1f0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 rently 3) */. i
d200: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
d210: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
d220: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
d230: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
d240: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
d250: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
d260: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
d270: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
d280: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
d290: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
d2a0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
d2b0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
d2c0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
d2d0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
d2e0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
d2f0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
d300: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
d310: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
d320: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
d330: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
d340: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
d350: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
d360: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
d370: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
d380: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
d390: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
d3a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
d3b0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
d3c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
d3d0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
d3e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
d3f0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
d400: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
d410: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
d420: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
d430: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
d440: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
d450: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
d460: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
d470: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
d480: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
d490: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
d4a0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
d4b0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
d4c0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
d4d0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
d4e0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
d4f0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
d500: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
d510: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
d520: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
d530: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
d540: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
d550: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
d560: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
d570: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
d580: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
d590: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
d5a0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
d5b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
d5c0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
d5d0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
d5e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
d5f0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
d600: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
d610: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
d620: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
d630: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
d640: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
d650: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 version 1 of the
d660: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
d670: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 ct. ** definiti
d680: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 on. Those that
d690: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 follow are added
d6a0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 in version 2 or
d6b0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e later. */. in
d6c0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
d6d0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 Int64)(sqlite3_v
d6e0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 fs*, sqlite3_int
d6f0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 64*);. /*. **
d700: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
d710: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
d720: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 s 1 and 2 of the
d730: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
d740: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 ct.. ** Those b
d750: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 elow are for ver
d760: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 sion 3 and great
d770: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 er.. */. int (
d780: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xSetSystemCall)
d790: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
d7a0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
d7b0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c , sqlite3_syscal
d7c0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 l_ptr);. sqlite
d7d0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 3_syscall_ptr (*
d7e0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xGetSystemCall)(
d7f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
d800: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
d810: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ;. const char *
d820: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c (*xNextSystemCal
d830: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
d840: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
d850: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 me);. /*. ** T
d860: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
d870: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
d880: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 1 through 3 of
d890: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
d8a0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 bject.. ** New
d8b0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
d8c0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 pended in figure
d8d0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 versions. The
d8e0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 iVersion. ** va
d8f0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 lue will increme
d900: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 nt whenever this
d910: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a happens. . */.
d920: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
d930: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
d940: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 e xAccess VFS me
d950: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
d960: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
d970: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
d980: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
d990: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
d9a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
d9b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
d9c0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 s] object. They
d9d0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
d9e0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
d9f0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
da00: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
da10: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
da20: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
da30: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
da40: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
da50: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
da60: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
da70: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
da80: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
da90: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
daa0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
dab0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e ks whether the n
dac0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 amed directory i
dad0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
dae0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 and writable.**
daf0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c (in other words,
db00: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 if files can be
db10: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c added, removed,
db20: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 and renamed wit
db30: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 hin.** the direc
db40: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 tory)..** The SQ
db50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
db60: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 WRITE constant i
db70: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 s currently used
db80: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 only by the.**
db90: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
dba0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 ctory pragma], t
dbb0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 hough this could
dbc0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
dbd0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
dbe0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 f SQLite..** Wit
dbf0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
dc00: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
dc10: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
dc20: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
dc30: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
dc40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 The SQLITE_ACC
dc50: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e ESS_READ constan
dc60: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c t is.** currentl
dc70: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 y unused, though
dc80: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 it might be use
dc90: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 d in a future re
dca0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
dcb0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
dcc0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
dcd0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
dce0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
dcf0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 EADWRITE 1 /*
dd00: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 Used by PRAGMA t
dd10: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
dd20: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ory */.#define S
dd30: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
dd40: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e D 2 /* Un
dd50: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
dd60: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
dd70: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 or the xShmLock
dd80: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
dd90: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
dda0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
ddb0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b the various lock
ddc0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ing operations.*
ddd0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 * allowed by the
dde0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
ddf0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f of [sqlite3_io_
de00: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a methods]. The.*
de10: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 * following are
de20: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 the only legal c
de30: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 ombinations of f
de40: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 lags to the.** x
de50: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a ShmLock method:.
de60: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
de70: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
de80: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
de90: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
dea0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
deb0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
dec0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CLUSIVE.** <li>
ded0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
dee0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
def0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
df00: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
df10: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
df20: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c XCLUSIVE.** </ul
df30: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c >.**.** When unl
df40: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 ocking, the same
df50: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 SHARED or EXCLU
df60: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 SIVE flag must b
df70: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a e supplied as.**
df80: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 was given no th
df90: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
dfa0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 lock. .**.** Th
dfb0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
dfc0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e d can transition
dfd0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
dfe0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a d and SHARED or.
dff0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 ** between unloc
e000: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 ked and EXCLUSIV
e010: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 E. It cannot tr
e020: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
e030: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 SHARED.** and E
e040: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 XCLUSIVE..*/.#de
e050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
e060: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 UNLOCK 1.#
e070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
e080: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 M_LOCK 2
e090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e0a0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 SHM_SHARED
e0b0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
e0c0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 E_SHM_EXCLUSIVE
e0d0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8../*.** CAPI
e0e0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 3REF: Maximum xS
e0f0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a hmLock index.**.
e100: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
e110: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 method on [sqlit
e120: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d e3_io_methods] m
e130: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a ay use values.**
e140: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
e150: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 his upper bound
e160: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 as its "offset"
e170: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
e180: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c SQLite core wil
e190: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 l never attempt
e1a0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 to acquire or re
e1b0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 lease a.** lock
e1c0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 outside of this
e1d0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 range.*/.#define
e1e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 SQLITE_SHM_NLOC
e1f0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a K 8.../*.
e200: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
e210: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
e220: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
e230: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
e240: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
e250: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
e260: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
e270: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 rary. ^The sqli
e280: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 te3_shutdown() r
e290: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f outine.** deallo
e2a0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 cates any resour
e2b0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c ces that were al
e2c0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
e2d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
e2e0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
e2f0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 es are designed
e300: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 to aid in proces
e310: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
e320: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e and.** shutdown
e330: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 on embedded sys
e340: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 tems. Workstati
e350: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 on applications
e360: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 using.** SQLite
e370: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 normally do not
e380: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 need to invoke e
e390: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 ither of these r
e3a0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 outines..**.** A
e3b0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
e3c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
e3d0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
e3e0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
e3f0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
e400: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e410: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
e420: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
e430: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
e440: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
e450: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
e460: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
e470: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
e480: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
e490: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
e4a0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 _shutdown(). ^(
e4b0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
e4c0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
e4d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e4e0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
e4f0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
e500: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
e510: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
e520: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ps.)^.**.** A ca
e530: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
e540: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 utdown() is an "
e550: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
e560: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
e570: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 st.** call to sq
e580: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
e590: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 since the last
e5a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e5b0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a ze(). ^(Only.**
e5c0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
e5d0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
e5e0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
e5f0: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
e600: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
e610: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 valid calls to
e620: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
e630: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 () are harmless
e640: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
e650: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
e660: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 ialize() interfa
e670: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ce is threadsafe
e680: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 , but sqlite3_sh
e690: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e utdown().** is n
e6a0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ot. The sqlite3
e6b0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 _shutdown() inte
e6c0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 rface must only
e6d0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 be called from a
e6e0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 .** single threa
e6f0: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 d. All open [da
e700: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
e710: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 ns] must be clos
e720: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 ed and all.** ot
e730: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 her SQLite resou
e740: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 rces must be dea
e750: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 llocated prior t
e760: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 o invoking.** sq
e770: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
e780: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
e790: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c her things, ^sql
e7a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e7b0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a ) will invoke.**
e7c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
e7d0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
e7e0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 ^sqlite3_shutdow
e7f0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
e800: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
e810: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 d()..**.** ^The
e820: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e830: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
e840: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
e850: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
e860: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ^If for some rea
e870: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 son, sqlite3_ini
e880: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 tialize() is una
e890: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a ble to initializ
e8a0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 e.** the library
e8b0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 (perhaps it is
e8c0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
e8d0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f te a needed reso
e8e0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 urce such.** as
e8f0: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 a mutex) it retu
e900: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f rns an [error co
e910: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b de] other than [
e920: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
e930: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
e940: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
e950: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e ine is called in
e960: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 ternally by many
e970: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
e980: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 interfaces so t
e990: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 hat an applicati
e9a0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 on usually does
e9b0: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 not need to.** i
e9c0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
e9d0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
e9e0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tly. For exampl
e9f0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e e, [sqlite3_open
ea00: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c ()].** calls sql
ea10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
ea20: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 ) so the SQLite
ea30: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 library will be
ea40: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
ea50: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 initialized whe
ea60: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 n [sqlite3_open(
ea70: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 )] is called if
ea80: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e it has not be in
ea90: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 itialized.** alr
eaa0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c eady. ^However,
eab0: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
eac0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
ead0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
eae0: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c OINIT].** compil
eaf0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 e-time option, t
eb00: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 hen the automati
eb10: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 c calls to sqlit
eb20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
eb30: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 ** are omitted a
eb40: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
eb50: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c on must call sql
eb60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
eb70: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 ) directly.** pr
eb80: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
eb90: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
eba0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 terface. For ma
ebb0: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 ximum portabilit
ebc0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f y,.** it is reco
ebd0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
ebe0: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 lications always
ebf0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
ec00: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
ec10: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 directly prior t
ec20: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
ec30: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
ec40: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 ce. Future rele
ec50: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ases.** of SQLit
ec60: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 e may require th
ec70: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f is. In other wo
ec80: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f rds, the behavio
ec90: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 r exhibited.** w
eca0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
ecb0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
ecc0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
ecd0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 T] might become
ece0: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 the.** default b
ecf0: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 ehavior in some
ed00: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
ed10: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
ed20: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
ed30: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f nit() routine do
ed40: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 es operating-sys
ed50: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 tem specific.**
ed60: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
ed70: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
ed80: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
ed90: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 e3_os_end().** r
eda0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 outine undoes th
edb0: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 e effect of sqli
edc0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
edd0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a Typical tasks.**
ede0: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 performed by th
edf0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 ese routines inc
ee00: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 lude allocation
ee10: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a or deallocation.
ee20: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 ** of static res
ee30: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 ources, initiali
ee40: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c zation of global
ee50: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 variables,.** s
ee60: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 etting up a defa
ee70: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
ee80: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 ] module, or set
ee90: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 ting up.** a def
eea0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
eeb0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
eec0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 3_config()]..**.
eed0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
eee0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
eef0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 invoke either sq
ef00: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
ef10: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 ** or sqlite3_os
ef20: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e _end() directly.
ef30: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
ef40: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e n should only in
ef50: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
ef60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
ef70: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
ef80: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 n(). The sqlite
ef90: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 3_os_init().** i
efa0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c nterface is call
efb0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
efc0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
efd0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 ialize() and.**
efe0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
eff0: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 is called by sq
f000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f010: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a . Appropriate.*
f020: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
f030: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 s for sqlite3_os
f040: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
f050: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
f060: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 are built into S
f070: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 QLite when it is
f080: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e compiled for Un
f090: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 ix, Windows, or
f0a0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 OS/2..** When [c
f0b0: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 ustom builds | b
f0c0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
f0d0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 latforms].** (us
f0e0: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
f0f0: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
f100: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
f110: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
f120: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
f130: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
f140: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
f150: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
f160: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
f170: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
f180: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
f190: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
f1a0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
f1b0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
f1c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
f1d0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
f1e0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
f1f0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
f200: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
f210: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
f220: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
f230: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
f240: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 lize(void);.SQLI
f250: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
f260: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 e3_shutdown(void
f270: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
f280: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
f290: 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f t(void);.SQLITE_
f2a0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
f2b0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
f2c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
f2d0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
f2e0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
f2f0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
f300: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
f310: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
f320: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
f330: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
f340: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
f350: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
f360: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
f370: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
f380: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
f390: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
f3a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
f3b0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
f3c0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
f3d0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
f3e0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
f3f0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
f400: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
f410: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
f420: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
f430: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
f440: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 needs..**.** The
f450: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
f460: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
f470: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 ot threadsafe.
f480: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a The application.
f490: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 ** must insure t
f4a0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c hat no other SQL
f4b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
f4c0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 re invoked by ot
f4d0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 her.** threads w
f4e0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e hile sqlite3_con
f4f0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 fig() is running
f500: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 . Furthermore,
f510: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f520: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 .** may only be
f530: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f invoked prior to
f540: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c library initial
f550: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a ization using.**
f560: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
f570: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
f580: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 shutdown by [sq
f590: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f5a0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
f5b0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 3_config() is ca
f5c0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
f5d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f5e0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 ] and before.**
f5f0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
f600: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c n()] then it wil
f610: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f l return SQLITE_
f620: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c MISUSE..** Note,
f630: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e however, that ^
f640: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f650: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
f660: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
f670: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
f680: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f of an applicatio
f690: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 n-defined [sqlit
f6a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a e3_os_init()]..*
f6b0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
f6c0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
f6d0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 e3_config() is a
f6e0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f n integer.** [co
f6f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
f700: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 on] that determi
f710: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 nes.** what prop
f720: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 erty of SQLite i
f730: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 s to be configur
f740: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 ed. Subsequent
f750: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 arguments.** var
f760: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 y depending on t
f770: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f he [configuratio
f780: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
f790: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
f7a0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 nt..**.** ^When
f7b0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
f7c0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
f7d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
f7e0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
f7f0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 OK]..** ^If the
f800: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
f810: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
f820: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
f830: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
f840: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
f850: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
f860: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f [error code]..*/
f870: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
f880: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 sqlite3_config(i
f890: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a nt, ...);../*.**
f8a0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
f8b0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f gure database co
f8c0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 nnections.**.**
f8d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 The sqlite3_db_c
f8e0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
f8f0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
f900: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a e configuration.
f910: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 ** changes to a
f920: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
f930: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 tion]. The inte
f940: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 rface is similar
f950: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
f960: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 config()] except
f970: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 that the change
f980: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e s apply to a sin
f990: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 gle.** [database
f9a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 connection] (sp
f9b0: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 ecified in the f
f9c0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a irst argument)..
f9d0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
f9e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
f9f0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 ite3_db_config(D
fa00: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a ,V,...) is the.
fa10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e ** [SQLITE_DBCON
fa20: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 FIG_LOOKASIDE |
fa30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
fa40: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 rb] - an integer
fa50: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 code .** that i
fa60: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 ndicates what as
fa70: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
fa80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
fa90: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
faa0: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 gured..** Subseq
fab0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 uent arguments v
fac0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
fad0: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
fae0: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e on verb..**.** ^
faf0: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
fb00: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 _db_config() ret
fb10: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
fb20: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
fb30: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 the call is cons
fb40: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 idered successfu
fb50: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l..*/.SQLITE_API
fb60: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f int sqlite3_db_
fb70: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c config(sqlite3*,
fb80: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a int op, ...);..
fb90: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
fba0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
fbb0: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a n Routines.**.**
fbc0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
fbd0: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 this object defi
fbe0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
fbf0: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 e between SQLite
fc00: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 .** and low-leve
fc10: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
fc20: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
fc30: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
fc40: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 is used in only
fc50: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 one place in the
fc60: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
fc70: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 e..** A pointer
fc80: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
fc90: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 f this object is
fca0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
fcb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
fcc0: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 fig()] when the
fcd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
fce0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 tion is.** [SQLI
fcf0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
fd00: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
fd10: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 FIG_GETMALLOC].
fd20: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 .** By creating
fd30: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
fd40: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 this object.** a
fd50: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f nd passing it to
fd60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
fd70: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
fd80: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 _MALLOC]).** dur
fd90: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
fda0: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f n, an applicatio
fdb0: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e n can specify an
fdc0: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
fdd0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
fde0: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 n subsystem for
fdf0: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f SQLite to use fo
fe00: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 r all of its.**
fe10: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e dynamic memory n
fe20: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 eeds..**.** Note
fe30: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d that SQLite com
fe40: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 es with several
fe50: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 [built-in memory
fe60: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 allocators].**
fe70: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 that are perfect
fe80: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 ly adequate for
fe90: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 the overwhelming
fea0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 majority of app
feb0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 lications.** and
fec0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 that this objec
fed0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c t is only useful
fee0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 to a tiny minor
fef0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
ff00: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 ons.** with spec
ff10: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 ialized memory a
ff20: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 llocation requir
ff30: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 ements. This ob
ff40: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 ject is.** also
ff50: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
ff60: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e ing of SQLite in
ff70: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 order to specif
ff80: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
ff90: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
ffa0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 ator that simula
ffb0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f tes memory out-o
ffc0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 f-memory conditi
ffd0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 ons in.** order
ffe0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 to verify that S
fff0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 QLite recovers g
10000 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 racefully from s
10010 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e uch.** condition
10020 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 s..**.** The xMa
10030 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 lloc, xRealloc,
10040 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 and xFree method
10050 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 s must work like
10060 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 the.** malloc()
10070 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 , realloc() and
10080 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 free() functions
10090 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
100a0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
100b0 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
100c0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 ees that the sec
100d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
100e0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 ** xRealloc is a
100f0 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 lways a value re
10100 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f turned by a prio
10110 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 r call to xRound
10120 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 up..**.** xSize
10130 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
10140 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
10150 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c of a memory all
10160 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 ocation.** previ
10170 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
10180 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 rom xMalloc or x
10190 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c Realloc. The al
101a0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 located size.**
101b0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 is always at lea
101c0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 st as big as the
101d0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 requested size
101e0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
101f0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f r..**.** The xRo
10200 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 undup method ret
10210 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 urns what would
10220 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 be the allocated
10230 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 size of.** a me
10240 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
10250 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c given a particul
10260 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a ar requested siz
10270 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a e. Most memory.
10280 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f ** allocators ro
10290 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c und up memory al
102a0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 locations at lea
102b0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d st to the next m
102c0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e ultiple.** of 8.
102d0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 Some allocator
102e0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 s round up to a
102f0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 larger multiple
10300 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 or to a power of
10310 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 2..** Every mem
10320 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
10330 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e equest coming in
10340 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 through [sqlite
10350 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 3_malloc()].** o
10360 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
10370 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c oc()] first call
10380 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 s xRoundup. If
10390 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 xRoundup returns
103a0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 0, .** that cau
103b0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f ses the correspo
103c0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c nding memory all
103d0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e ocation to fail.
103e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
103f0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
10400 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
10410 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 llocator. (For
10420 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
10430 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
10440 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
10450 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
10460 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
10470 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
10480 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
10490 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
104a0 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
104b0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
104c0 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
104d0 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
104e0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
104f0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
10500 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
10510 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
10520 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
10530 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
10540 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
10550 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
10560 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
10570 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
10580 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
10590 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
105a0 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
105b0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
105c0 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
105d0 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
105e0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
105f0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
10600 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
10610 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
10620 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
10630 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
10640 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
10650 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
10660 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
10670 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
10680 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
10690 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
106a0 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
106b0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
106c0 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
106d0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
106e0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
106f0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
10700 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
10710 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
10720 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
10730 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
10740 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
10750 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
10760 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
10770 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
10780 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
10790 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
107a0 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
107b0 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
107c0 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
107d0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
107e0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
107f0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
10800 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
10810 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
10820 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
10830 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
10840 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
10850 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
10860 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
10870 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
10880 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
10890 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
108a0 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
108b0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
108c0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
108d0 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
108e0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
108f0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
10900 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
10910 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
10920 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
10930 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
10940 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
10950 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
10960 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
10970 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
10980 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
10990 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
109a0 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
109b0 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
109c0 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
109d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
109e0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
109f0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
10a00 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
10a10 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
10a20 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
10a30 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
10a40 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
10a50 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
10a60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
10a70 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
10a80 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
10a90 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
10aa0 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
10ab0 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
10ac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10ad0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
10ae0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ptions.** KEYWOR
10af0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 DS: {configurati
10b00 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a on option}.**.**
10b10 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
10b20 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
10b30 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
10b40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
10b50 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
10b60 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
10b70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
10b80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
10b90 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
10ba0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
10bb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10bc0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
10bd0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
10be0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
10bf0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
10c00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
10c10 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
10c20 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
10c30 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
10c40 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
10c50 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
10c60 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
10c70 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
10c80 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
10c90 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
10ca0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
10cb0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
10cc0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
10cd0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
10ce0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
10cf0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
10d00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10d10 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
10d20 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
10d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
10d40 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 NGLETHREAD]] <dt
10d50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
10d60 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
10d70 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
10d80 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
10d90 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
10da0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
10db0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
10dc0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e ing mode] to Sin
10dd0 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 gle-thread. In
10de0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
10df0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 disables.** all
10e00 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 mutexing and put
10e10 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 s SQLite into a
10e20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 mode where it ca
10e30 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a n only be used.*
10e40 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 * by a single th
10e50 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 read. ^If SQLi
10e60 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
10e70 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
10e80 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
10e90 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
10ea0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
10eb0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
10ec0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
10ed0 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ble to change th
10ee0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
10ef0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 e] from its defa
10f00 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 ult.** value of
10f10 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e Single-thread an
10f20 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f d so [sqlite3_co
10f30 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
10f40 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urn .** [SQLITE_
10f50 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
10f60 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
10f70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
10f80 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 READ.** configur
10f90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
10fa0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
10fb0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
10fc0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
10fd0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
10fe0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
10ff0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
11000 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
11010 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
11020 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
11030 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
11040 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 e] to Multi-thre
11050 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
11060 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
11070 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
11080 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
11090 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
110a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
110b0 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
110c0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
110d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
110e0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
110f0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
11100 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
11110 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
11120 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
11130 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
11140 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
11150 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
11160 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
11170 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
11180 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
11190 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 as long as no t
111a0 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d wo threads attem
111b0 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 pt to use the sa
111c0 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 me.** [database
111d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 connection] at t
111e0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e he same time. ^
111f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
11200 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
11210 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
11220 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
11230 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
11240 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
11250 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
11260 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
11270 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 t the Multi-thre
11280 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
11290 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
112a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
112b0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
112c0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
112d0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
112e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
112f0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 TITHREAD configu
11300 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
11310 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
11320 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
11330 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 IZED]] <dt>SQLIT
11340 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
11350 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
11360 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
11370 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
11380 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
11390 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
113a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
113b0 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e ] to Serialized.
113c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
113d0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 this option ena
113e0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
113f0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
11400 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
11410 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
11420 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
11430 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
11440 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
11450 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
11460 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
11470 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
11480 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11490 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
114a0 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
114b0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
114c0 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
114d0 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
114e0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
114f0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
11500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
11510 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
11520 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
11530 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
11540 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
11550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
11560 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
11570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
11580 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
11590 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
115a0 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 ame time..** ^If
115b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
115c0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
115d0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
115e0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
115f0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
11600 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
11610 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
11620 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
11630 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b the Serialized [
11640 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
11650 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
11660 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
11670 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
11680 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
11690 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
116a0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
116b0 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ZED configuratio
116c0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
116d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
116e0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 NFIG_MALLOC]] <d
116f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
11700 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
11710 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
11720 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
11730 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
11740 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
11750 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
11760 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
11770 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
11780 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
11790 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
117a0 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
117b0 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
117c0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
117d0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
117e0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
117f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11800 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
11810 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
11820 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a ^SQLite makes.*
11830 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 * its own privat
11840 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f e copy of the co
11850 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
11860 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
11870 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 s] structure.**
11880 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 before the [sqli
11890 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 te3_config()] ca
118a0 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e ll returns.</dd>
118b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
118c0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
118d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
118e0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f NFIG_GETMALLOC</
118f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
11900 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
11910 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
11920 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
11930 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
11940 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
11950 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
11960 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
11970 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
11980 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
11990 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
119a0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
119b0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
119c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
119d0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
119e0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
119f0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
11a00 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
11a10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
11a20 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
11a30 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
11a40 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
11a50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
11a60 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
11a70 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
11a80 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 for example. </d
11a90 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
11aa0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
11ab0 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f US]] <dt>SQLITE_
11ac0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
11ad0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
11ae0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
11af0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
11b00 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e of type int, in
11b10 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a terpreted as a .
11b20 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 ** boolean, whic
11b30 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 h enables or dis
11b40 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 ables the collec
11b50 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 tion of memory a
11b60 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 llocation .** st
11b70 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e atistics. ^(When
11b80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11b90 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
11ba0 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 e disabled, the
11bb0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 .** following SQ
11bc0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
11bd0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 become non-opera
11be0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c tional:.** <ul
11bf0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c >.** <li> [sql
11c00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
11c10 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
11c20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
11c30 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 ghwater()].**
11c40 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f <li> [sqlite3_so
11c50 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
11c60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
11c70 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a lite3_status()].
11c80 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ** </ul>)^.**
11c90 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 ^Memory allocati
11ca0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
11cb0 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
11cc0 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 ault unless SQLi
11cd0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 te is.** compile
11ce0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 d with [SQLITE_D
11cf0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 EFAULT_MEMSTATUS
11d00 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 ]=0 in which cas
11d10 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
11d20 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
11d30 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
11d40 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f y default..** </
11d50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
11d60 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
11d70 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 H]] <dt>SQLITE_C
11d80 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
11d90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
11da0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
11db0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
11dc0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
11dd0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
11de0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
11df0 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
11e00 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
11e10 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
11e20 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
11e30 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
11e40 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
11e50 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 atch allocations
11e60 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 will be.** draw
11e70 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 n, the size of e
11e80 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f ach scratch allo
11e90 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 cation (sz),.**
11ea0 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 and the maximum
11eb0 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 number of scratc
11ec0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e h allocations (N
11ed0 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 ). The sz.** ar
11ee0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
11ef0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e multiple of 16.
11f00 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
11f10 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
11f20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
11f30 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 -byte aligned bu
11f40 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 ffer.** of at le
11f50 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
11f60 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
11f70 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f Lite will use no
11f80 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 more than two s
11f90 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 cratch buffers p
11fa0 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a er thread. So.*
11fb0 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 * N should be se
11fc0 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 t to twice the e
11fd0 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 xpected maximum
11fe0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 number of thread
11ff0 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 s..** ^SQLite wi
12000 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 ll never require
12010 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 a scratch buffe
12020 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 r that is more t
12030 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 han 6.** times t
12040 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
12050 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 size. ^If SQLit
12060 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 e needs needs ad
12070 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 ditional.** scra
12080 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e tch memory beyon
12090 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
120a0 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 ed by this confi
120b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c guration option,
120c0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 then .** [sqlit
120d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c e3_malloc()] wil
120e0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 l be used to obt
120f0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e ain the memory n
12100 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a eeded.</dd>.**.*
12110 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12120 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 G_PAGECACHE]] <d
12130 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12140 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
12150 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
12160 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
12170 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
12180 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
12190 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
121a0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
121b0 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 e cache with the
121c0 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 default page ca
121d0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
121e0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
121f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
12200 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
12210 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
12220 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
12230 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
12240 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
12250 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f sing the SQLITE_
12260 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f CONFIG_PCACHE2 o
12270 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 ption..** There
12280 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
12290 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
122a0 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f on: A pointer to
122b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 8-byte aligned.
122c0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 ** memory, the s
122d0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 ize of each page
122e0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e buffer (sz), an
122f0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
12300 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 pages (N)..** Th
12310 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 e sz argument sh
12320 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 ould be the size
12330 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
12340 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a database page.**
12350 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f (a power of two
12360 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
12370 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 32768) plus a l
12380 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 ittle extra for
12390 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
123a0 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 der. ^The page
123b0 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 header size is 2
123c0 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 0 to 40 bytes de
123d0 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 pending on.** th
123e0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 e host architect
123f0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 ure. ^It is har
12400 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f mless, apart fro
12410 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d m the wasted mem
12420 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 ory,.** to make
12430 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 sz a little too
12440 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 large. The firs
12450 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
12460 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
12470 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
12480 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
12490 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
124a0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
124b0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
124c0 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
124d0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
124e0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
124f0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
12500 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
12510 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
12520 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 cache. ^If add
12530 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
12540 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
12550 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
12560 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
12570 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 y this option, t
12580 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f hen.** SQLite go
12590 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
125a0 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 alloc()] for the
125b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 additional stor
125c0 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 age space..** Th
125d0 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
125e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
125f0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
12600 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
12610 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
12620 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
12630 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
12640 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
12650 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12660 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d ITE_CONFIG_HEAP]
12670 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12680 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a FIG_HEAP</dt>.**
12690 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
126a0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
126b0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
126c0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
126d0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 will use.** for
126e0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
126f0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ic memory alloca
12700 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e tion needs beyon
12710 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 d those provided
12720 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 .** for by [SQLI
12730 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
12740 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 H] and [SQLITE_C
12750 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
12760 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 ..** There are t
12770 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
12780 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 An 8-byte aligne
12790 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 d pointer to the
127a0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 memory,.** the
127b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
127c0 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
127d0 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
127e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
127f0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 size..** ^If th
12800 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
12810 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
12820 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
12830 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
12840 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
12850 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
12860 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
12870 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
12880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
12890 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
128a0 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
128b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
128c0 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 IG_MALLOC]. ^If
128d0 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 the.** memory p
128e0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
128f0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 LL and either [S
12900 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
12910 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c SYS3] or.** [SQL
12920 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
12930 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c S5] are defined,
12940 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e then the altern
12950 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ative memory.**
12960 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 allocator is eng
12970 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 aged to handle a
12980 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 ll of SQLites me
12990 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
129a0 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 needs..** The fi
129b0 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
129c0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
129d0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
129e0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
129f0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 boundary or sub
12a00 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
12a10 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 of SQLite will
12a20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a be undefined..**
12a30 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c The minimum all
12a40 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 ocation size is
12a50 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e capped at 2**12.
12a60 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 Reasonable valu
12a70 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 es.** for the mi
12a80 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
12a90 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 size are 2**5 t
12aa0 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 hrough 2**8.</dd
12ab0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12ac0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 _CONFIG_MUTEX]]
12ad0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
12ae0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 G_MUTEX</dt>.**
12af0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
12b00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12b10 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12b20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
12b30 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
12b40 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
12b50 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
12b60 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 tructure. The a
12b70 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
12b80 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 s.** alternative
12b90 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 low-level mutex
12ba0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
12bb0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a used in place.**
12bc0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 the mutex routi
12bd0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
12be0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 QLite.)^ ^SQLit
12bf0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
12c00 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 f the.** content
12c10 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
12c20 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
12c30 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 structure before
12c40 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
12c50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12c60 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 )] returns. ^If
12c70 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
12c80 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
12c90 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
12ca0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
12cb0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
12cc0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
12cd0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 n.** the entire
12ce0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 mutexing subsyst
12cf0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 em is omitted fr
12d00 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 om the build and
12d10 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a hence calls to.
12d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
12d30 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 ig()] with the S
12d40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
12d50 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
12d60 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
12d70 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
12d80 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
12d90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12da0 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 G_GETMUTEX]] <dt
12db0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
12dc0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
12dd0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
12de0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12df0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12e00 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
12e10 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
12e20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
12e30 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
12e40 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
12e50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
12e60 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
12e70 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
12e80 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
12e90 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
12ea0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
12eb0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
12ec0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
12ed0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
12ee0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
12ef0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
12f00 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
12f10 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
12f20 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
12f30 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
12f40 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
12f50 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
12f60 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
12f70 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
12f80 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
12f90 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
12fa0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
12fb0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
12fc0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
12fd0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
12fe0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
12ff0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
13000 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
13010 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
13020 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
13030 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13040 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
13050 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
13060 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
13070 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
13080 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
13090 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
130a0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
130b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
130c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
130d0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
130e0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 two arguments t
130f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
13100 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d e default.** mem
13110 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
13120 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 or the lookaside
13130 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
13140 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 r on each.** [da
13150 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
13160 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 n]. The first a
13170 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
13180 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
13190 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
131a0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 slot and the sec
131b0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ond is the numbe
131c0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c r of.** slots al
131d0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 located to each
131e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
131f0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f ion.)^ ^(This o
13200 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
13210 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e * <i>default</i>
13220 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e lookaside size.
13230 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 The [SQLITE_DBC
13240 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
13250 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c .** verb to [sql
13260 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
13270 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ] can be used to
13280 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
13290 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 aside.** configu
132a0 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 ration on indivi
132b0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 dual connections
132c0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
132d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
132e0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 PCACHE2]] <dt>SQ
132f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
13300 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
13310 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
13320 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
13330 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
13340 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
13350 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
13360 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
13370 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
13380 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
13390 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
133a0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
133b0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
133c0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d on.)^ ^SQLite m
133d0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
133e0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 he.** object and
133f0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 uses it for pag
13400 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 e cache memory a
13410 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e llocations.</dd>
13420 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
13430 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
13440 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
13450 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
13460 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
13470 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
13480 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
13490 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
134a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
134b0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
134c0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
134d0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
134e0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
134f0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d ** page cache im
13500 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
13510 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
13520 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
13530 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
13540 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
13550 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
13560 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 <dd> The SQLITE
13570 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
13580 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f on is used to co
13590 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 nfigure the SQLi
135a0 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 te.** global [er
135b0 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 ror log]..** (^T
135c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
135d0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _LOG option take
135e0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a s two arguments:
135f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a a pointer to a.
13600 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ** function with
13610 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 a call signatur
13620 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 e of void(*)(voi
13630 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
13640 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 r*), .** and a p
13650 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 ointer to void.
13660 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ^If the function
13670 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
13680 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 NULL, it is.** i
13690 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 nvoked by [sqlit
136a0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f e3_log()] to pro
136b0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e cess each loggin
136c0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
136d0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f e.** function po
136e0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 inter is NULL, t
136f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 he [sqlite3_log(
13700 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 )] interface bec
13710 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a omes a no-op..**
13720 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 ^The void point
13730 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 er that is the s
13740 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
13750 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
13760 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 LOG is.** passed
13770 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
13780 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
13790 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
137a0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
137b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 r.** function wh
137c0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 enever that func
137d0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e tion is invoked.
137e0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ^The second pa
137f0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
13800 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
13810 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 n is a copy of t
13820 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
13830 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 er to the corres
13840 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 ponding.** [sqli
13850 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 te3_log()] call
13860 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 and is intended
13870 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 to be a [result
13880 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b code] or an.** [
13890 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
138a0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 code]. ^The thi
138b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 rd parameter pas
138c0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 sed to the logge
138d0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 r is.** log mess
138e0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 age after format
138f0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 ting via [sqlite
13900 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 3_snprintf()]..*
13910 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 * The SQLite log
13920 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 ging interface i
13930 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b s not reentrant;
13940 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
13950 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 tion.** supplied
13960 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
13970 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 ion must not inv
13980 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 oke any SQLite i
13990 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 nterface..** In
139a0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
139b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
139c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
139d0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
139e0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 function must be
139f0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 threadsafe. </d
13a00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
13a10 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c E_CONFIG_URI]] <
13a20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13a30 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 _URI.** <dd> Thi
13a40 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
13a50 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
13a60 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 of type int. If
13a70 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a non-zero, then.
13a80 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 ** URI handling
13a90 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 is globally enab
13aa0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 led. If the para
13ab0 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 meter is zero, t
13ac0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 hen URI handling
13ad0 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 .** is globally
13ae0 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 disabled. If URI
13af0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
13b00 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 bally enabled, a
13b10 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 ll filenames.**
13b20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
13b30 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
13b40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
13b50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
13b60 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 ()] or.** specif
13b70 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b ied as part of [
13b80 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 ATTACH] commands
13b90 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
13ba0 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 as URIs, regard
13bb0 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 less.** of wheth
13bc0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 er or not the [S
13bd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
13be0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
13bf0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
13c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
13c10 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 pened. If it is
13c20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 globally disable
13c30 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 d, filenames are
13c40 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 .** only interpr
13c50 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 eted as URIs if
13c60 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f the SQLITE_OPEN_
13c70 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 URI flag is set
13c80 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 when the.** data
13c90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
13ca0 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 is opened. By de
13cb0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c fault, URI handl
13cc0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a ing is globally.
13cd0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 ** disabled. The
13ce0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d default value m
13cf0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 ay be changed by
13d00 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 compiling with
13d10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 the.** [SQLITE_U
13d20 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 SE_URI] symbol d
13d30 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b efined..**.** [[
13d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
13d50 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
13d60 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 N]] <dt>SQLITE_C
13d70 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
13d80 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 NDEX_SCAN.** <dd
13d90 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 > This option ta
13da0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 kes a single int
13db0 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 eger argument wh
13dc0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 ich is interpret
13dd0 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 ed as.** a boole
13de0 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 an in order to e
13df0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
13e00 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 the use of cove
13e10 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 ring indices for
13e20 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 .** full table s
13e30 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 cans in the quer
13e40 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 y optimizer. Th
13e50 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
13e60 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a g is determined.
13e70 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ** by the [SQLIT
13e80 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 E_ALLOW_COVERING
13e90 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d _INDEX_SCAN] com
13ea0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
13eb0 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 , or is "on".**
13ec0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d if that compile-
13ed0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f time option is o
13ee0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 mitted..** The a
13ef0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c bility to disabl
13f00 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 e the use of cov
13f10 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
13f20 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 r full table sca
13f30 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 ns.** is because
13f40 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c some incorrectl
13f50 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 y coded legacy a
13f60 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 pplications migh
13f70 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a t malfunction.**
13f80 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 malfunction whe
13f90 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 n the optimizati
13fa0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 on is enabled.
13fb0 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 Providing the ab
13fc0 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 ility to.** disa
13fd0 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 ble the optimiza
13fe0 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 tion allows the
13ff0 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 older, buggy app
14000 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f lication code to
14010 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 work.** without
14020 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 change even wit
14030 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 h newer versions
14040 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
14050 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14060 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c G_PCACHE]] [[SQL
14070 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
14080 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 ACHE]].** <dt>SQ
14090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
140a0 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f HE and SQLITE_CO
140b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a NFIG_GETPCACHE.*
140c0 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 * <dd> These opt
140d0 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 ions are obsolet
140e0 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 e and should not
140f0 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 be used by new
14100 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 code..** They ar
14110 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 e retained for b
14120 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
14130 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e bility but are n
14140 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f ow no-ops..** </
14150 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14160 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
14170 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
14180 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a _CONFIG_SQLLOG.*
14190 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
141a0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
141b0 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 ble if sqlite is
141c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
141d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
141e0 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 ABLE_SQLLOG] pre
141f0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f -processor macro
14200 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 defined. The fi
14210 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rst argument sho
14220 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e uld.** be a poin
14230 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f ter to a functio
14240 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a n of type void(*
14250 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
14260 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e ,const char*, in
14270 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e t)..** The secon
14280 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 d should be of t
14290 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 ype (void*). The
142a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
142b0 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 oked by the libr
142c0 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 ary.** in three
142d0 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 separate circums
142e0 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 tances, identifi
142f0 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 ed by the value
14300 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a passed as the.**
14310 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
14320 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 r. If the fourth
14330 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c parameter is 0,
14340 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
14350 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
14360 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
14370 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 econd argument h
14380 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 as just been ope
14390 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 ned. The third a
143a0 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 rgument.** point
143b0 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f s to a buffer co
143c0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d ntaining the nam
143d0 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 e of the main da
143e0 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 tabase file. If
143f0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
14400 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 rameter is 1, th
14410 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
14420 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 ment that the th
14430 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ird parameter.**
14440 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a points to has j
14450 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 ust been execute
14460 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f d. Or, if the fo
14470 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
14480 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 s 2, then.** the
14490 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e connection bein
144a0 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 g passed as the
144b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
144c0 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 is being closed
144d0 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 . The.** third p
144e0 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 arameter is pass
144f0 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 ed NULL In this
14500 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c case. An exampl
14510 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a e of using this.
14520 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
14530 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 option can be s
14540 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 een in the "test
14550 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 _sqllog.c" sourc
14560 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 e file in.** the
14570 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 canonical SQLit
14580 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f e source tree.</
14590 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
145a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
145b0 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IZE]].** <dt>SQL
145c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
145d0 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c 49 SIZE.** <dd>SQLI
145e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
145f0 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 IZE takes two 64
14600 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 -bit integer (sq
14610 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c lite3_int64) val
14620 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 ues.** that are
14630 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 the default mmap
14640 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 size limit (the
14650 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 default setting
14660 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 for.** [PRAGMA
14670 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 mmap_size]) and
14680 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f the maximum allo
14690 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 wed mmap size li
146a0 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 mit..** The defa
146b0 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 ult setting can
146c0 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 be overridden by
146d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
146e0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a onnection using.
146f0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 ** either the [P
14700 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
14710 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 command, or by
14720 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 using the.** [SQ
14730 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
14740 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 SIZE] file contr
14750 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d 75 6d ol. The maximum
14760 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 allowed mmap si
14770 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 ze.** cannot be
14780 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 changed at run-t
14790 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 ime. Nor may th
147a0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
147b0 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 d mmap size.** e
147c0 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c xceed the compil
147d0 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d e-time maximum m
147e0 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 map size set by
147f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d the.** [SQLITE_M
14800 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f AX_MMAP_SIZE] co
14810 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
14820 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74 68 65 n. .** If eithe
14830 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 r argument to th
14840 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 is option is neg
14850 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 ative, then that
14860 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
14870 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 changed to its c
14880 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 ompile-time defa
14890 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f ult..** </dl>.*/
148a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
148b0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
148c0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a EAD 1 /* nil *
148d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
148e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
148f0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 EAD 2 /* nil
14900 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14910 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
14920 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c ZED 3 /* nil
14930 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14940 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
14950 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 4 /* sq
14960 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
14970 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
14980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
14990 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 ALLOC 5 /*
149a0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
149b0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
149c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
149d0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f RATCH 6 /
149e0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
149f0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
14a00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14a10 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
14a20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
14a30 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
14a40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
14a50 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
14a60 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
14a70 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
14a80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14a90 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
14aa0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
14ab0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
14ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
14ad0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
14ae0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
14af0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
14b00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
14b10 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
14b20 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
14b30 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
14b40 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
14b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
14b60 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
14b70 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
14b80 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
14b90 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
14ba0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
14bb0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
14bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
14bd0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
14be0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
14bf0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
14c00 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
14c10 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
14c20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
14c30 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
14c40 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
14c50 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
14c60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
14c70 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f I 17 /
14c80 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
14c90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
14ca0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 CACHE2 18
14cb0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
14cc0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
14cd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
14ce0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
14cf0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 19 /* sqlite3
14d00 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
14d10 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
14d20 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
14d30 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 ING_INDEX_SCAN 2
14d40 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 0 /* int */.#de
14d50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
14d60 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 IG_SQLLOG
14d70 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 21 /* xSqllog,
14d80 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
14d90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
14da0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 MAP_SIZE 22
14db0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 /* sqlite3_int64
14dc0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
14dd0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
14de0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
14df0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 nection Configur
14e00 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
14e10 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
14e20 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
14e30 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
14e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14e50 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
14e60 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
14e70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
14e80 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
14e90 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e _db_config()] in
14ea0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
14eb0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
14ec0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
14ed0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
14ee0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
14ef0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
14f00 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14f10 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
14f20 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
14f30 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
14f40 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
14f50 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
14f60 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
14f70 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
14f80 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
14f90 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 all worked. ^Th
14fa0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
14fb0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
14fc0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a e will return a.
14fd0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 ** non-zero [err
14fe0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 or code] if a di
14ff0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e scontinued or un
15000 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 supported config
15010 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a uration option.*
15020 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a * is invoked..**
15030 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
15040 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
15050 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
15060 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
15070 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 ion takes three
15080 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
15090 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
150a0 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f ine the .** [loo
150b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c kaside memory al
150c0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
150d0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b ration for the [
150e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
150f0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 ion]..** ^The fi
15100 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 rst argument (th
15110 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
15120 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 r to [sqlite3_db
15130 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a _config()] is a.
15140 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 ** pointer to a
15150 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f memory buffer to
15160 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 use for lookasi
15170 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 de memory..** ^T
15180 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
15190 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 t after the SQLI
151a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
151b0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 ASIDE verb.** ma
151c0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 y be NULL in whi
151d0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 ch case SQLite w
151e0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 ill allocate the
151f0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 .** lookaside bu
15200 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e ffer itself usin
15210 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
15220 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e c()]. ^The secon
15230 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
15240 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
15250 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 h lookaside buff
15260 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 er slot. ^The t
15270 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
15280 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
15290 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 * slots. The si
152a0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
152b0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
152c0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 gument must be g
152d0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f reater than.** o
152e0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 r equal to the p
152f0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 roduct of the se
15300 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 cond and third a
15310 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 rguments. The b
15320 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 uffer.** must be
15330 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
15340 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 -byte boundary.
15350 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 ^If the second
15360 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 argument to.** S
15370 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
15380 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 OOKASIDE is not
15390 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c a multiple of 8,
153a0 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c it is internall
153b0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 y.** rounded dow
153c0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d n to the next sm
153d0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f aller multiple o
153e0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b f 8. ^(The look
153f0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 aside memory.**
15400 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
15410 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e r a database con
15420 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 nection can only
15430 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e be changed when
15440 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 that.** connect
15450 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 ion is not curre
15460 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 ntly using looka
15470 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 side memory, or
15480 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a in other words.*
15490 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 * when the "curr
154a0 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 ent value" retur
154b0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
154c0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c e3_db_status](D,
154d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
154e0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 OOKASIDE],...) i
154f0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 s zero..** Any a
15500 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 ttempt to change
15510 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d the lookaside m
15520 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 emory configurat
15530 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 ion when lookasi
15540 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 de.** memory is
15550 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 in use leaves th
15560 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
15570 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 unchanged and re
15580 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 turns .** [SQLIT
15590 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a E_BUSY].)^</dd>.
155a0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
155b0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
155c0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _FKEY</dt>.** <d
155d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
155e0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
155f0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 e or disable the
15600 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a enforcement of.
15610 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 ** [foreign key
15620 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 constraints]. T
15630 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
15640 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
15650 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 guments..** The
15660 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
15670 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
15680 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
15690 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
156a0 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 t,.** positive t
156b0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f o enable FK enfo
156c0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 rcement or negat
156d0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 ive to leave FK
156e0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 enforcement.** u
156f0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 nchanged. The s
15700 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
15710 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
15720 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
15730 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
15740 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
15750 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 dicate whether F
15760 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 K enforcement is
15770 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f off or on.** fo
15780 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
15790 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
157a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
157b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
157c0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
157d0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d the FK enforcem
157e0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e ent setting is n
157f0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
15800 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
15810 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
15820 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 G_ENABLE_TRIGGER
15830 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
15840 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
15850 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 ed to enable or
15860 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 disable [CREATE
15870 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 TRIGGER | trigge
15880 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 rs]..** There sh
15890 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 ould be two addi
158a0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
158b0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
158c0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e rgument is an in
158d0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 teger which is 0
158e0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 to disable trig
158f0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 gers,.** positiv
15900 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 e to enable trig
15910 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 gers or negative
15920 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 to leave the se
15930 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e tting unchanged.
15940 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
15950 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
15960 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
15970 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
15980 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
15990 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
159a0 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 whether triggers
159b0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 are disabled or
159c0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c enabled.** foll
159d0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
159e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
159f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 ameter may be a
15a00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
15a10 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 .** which case t
15a20 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 he trigger setti
15a30 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 ng is not report
15a40 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a ed back. </dd>.*
15a50 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 *.** </dl>.*/.#d
15a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
15a70 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
15a80 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 1001 /* v
15a90 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a oid* int int */.
15aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15ab0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 BCONFIG_ENABLE_F
15ac0 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a KEY 1002 /*
15ad0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
15ae0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
15af0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 NFIG_ENABLE_TRIG
15b00 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e GER 1003 /* in
15b10 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a t int* */.../*.*
15b20 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
15b30 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
15b40 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
15b50 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 des.**.** ^The s
15b60 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
15b70 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 result_codes() r
15b80 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f outine enables o
15b90 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a r disables the.*
15ba0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
15bb0 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 lt codes] featur
15bc0 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 e of SQLite. ^Th
15bd0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
15be0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 t.** codes are d
15bf0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
15c00 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 lt for historica
15c10 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e l compatibility.
15c20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
15c30 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
15c40 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
15c50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
15c60 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 noff);../*.** CA
15c70 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 PI3REF: Last Ins
15c80 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 ert Rowid.**.**
15c90 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 ^Each entry in a
15ca0 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 n SQLite table h
15cb0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
15cc0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
15cd0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
15ce0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f the [ROWID | "ro
15cf0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 wid"]. ^The rowi
15d00 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 d is always avai
15d10 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 lable.** as an u
15d20 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e ndeclared column
15d30 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 named ROWID, OI
15d40 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 D, or _ROWID_ as
15d50 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a long as those.*
15d60 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 * names are not
15d70 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 also used by exp
15d80 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
15d90 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a columns. ^If.**
15da0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
15db0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
15dc0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
15dd0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
15de0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
15df0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
15e00 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
15e10 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 ^This routine re
15e20 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 turns the [rowid
15e30 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ] of the most re
15e40 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 cent.** successf
15e50 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f ul [INSERT] into
15e60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 the database fr
15e70 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 om the [database
15e80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
15e90 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
15ea0 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 ument. ^As of S
15eb0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
15ec0 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 7.7, this routin
15ed0 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 es.** records th
15ee0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f e last insert ro
15ef0 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 wid of both ordi
15f00 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 nary tables and
15f10 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
15f20 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 ..** ^If no succ
15f30 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 essful [INSERT]s
15f40 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 .** have ever oc
15f50 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 curred on that d
15f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15f70 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 on, zero is retu
15f80 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 rned..**.** ^(If
15f90 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 an [INSERT] occ
15fa0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 urs within a tri
15fb0 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 gger or within a
15fc0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
15fd0 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e .** method, then
15fe0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
15ff0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 ll return the [r
16000 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 owid] of the ins
16010 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 erted.** row as
16020 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 long as the trig
16030 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 ger or virtual t
16040 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 able method is r
16050 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f unning..** But o
16060 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 nce the trigger
16070 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 or virtual table
16080 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 method ends, th
16090 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
160a0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 .** by this rou
160b0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 tine reverts to
160c0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f what it was befo
160d0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f re the trigger o
160e0 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 r virtual.** tab
160f0 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e le method began.
16100 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e )^.**.** ^An [IN
16110 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 SERT] that fails
16120 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 due to a constr
16130 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 aint violation i
16140 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 s not a.** succe
16150 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 ssful [INSERT] a
16160 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nd does not chan
16170 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ge the value ret
16180 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a urned by this.**
16190 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 routine. ^Thus
161a0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c INSERT OR FAIL,
161b0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 INSERT OR IGNOR
161c0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c E, INSERT OR ROL
161d0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e LBACK,.** and IN
161e0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 SERT OR ABORT ma
161f0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f ke no changes to
16200 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
16210 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 e of this.** rou
16220 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 tine when their
16230 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e insertion fails.
16240 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 ^(When INSERT
16250 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e OR REPLACE.** en
16260 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 counters a const
16270 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c raint violation,
16280 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 it does not fai
16290 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 l. The.** INSER
162a0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 T continues to c
162b0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 ompletion after
162c0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 deleting rows th
162d0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 at caused.** the
162e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 constraint prob
162f0 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 lem so INSERT OR
16300 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c REPLACE will al
16310 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 ways change.** t
16320 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
16330 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 of this interfac
16340 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 e.)^.**.** ^For
16350 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
16360 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e this routine, an
16370 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e [INSERT] is con
16380 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 sidered to.** be
16390 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e successful even
163a0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 if it is subseq
163b0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 uently rolled ba
163c0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 ck..**.** This f
163d0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 unction is acces
163e0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 sible to SQL sta
163f0 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a tements via the.
16400 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f ** [last_insert_
16410 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 rowid() SQL func
16420 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
16430 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
16440 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 d performs a new
16450 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 [INSERT] on the
16460 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 same.** databas
16470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 e connection whi
16480 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f le the [sqlite3_
16490 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
164a0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e d()].** function
164b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 is running and
164c0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 thus changes the
164d0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f last insert [ro
164e0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 wid],.** then th
164f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
16500 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 by [sqlite3_las
16510 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
16520 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 ] is.** unpredic
16530 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 table and might
16540 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 not equal either
16550 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 the old or the
16560 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 new.** last inse
16570 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 rt [rowid]..*/.S
16580 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
16590 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
165a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
165b0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a d(sqlite3*);../*
165c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
165d0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f unt The Number O
165e0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a f Rows Modified.
165f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
16600 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
16610 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 number of datab
16620 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 ase rows that we
16630 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 re changed.** or
16640 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c inserted or del
16650 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 eted by the most
16660 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 recently comple
16670 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
16680 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 t.** on the [dat
16690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
166a0 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 ] specified by t
166b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
166c0 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 er..** ^(Only ch
166d0 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 anges that are d
166e0 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 irectly specifie
166f0 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 d by the [INSERT
16700 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 ], [UPDATE],.**
16710 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 or [DELETE] stat
16720 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 ement are counte
16730 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 d. Auxiliary ch
16740 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a anges caused by.
16750 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b ** triggers or [
16760 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
16770 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 ons] are not cou
16780 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a nted.)^ Use the.
16790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 ** [sqlite3_tota
167a0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e l_changes()] fun
167b0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 ction to find th
167c0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
167d0 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 f changes.** inc
167e0 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 luding changes c
167f0 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 aused by trigger
16800 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 s and foreign ke
16810 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a y actions..**.**
16820 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 ^Changes to a v
16830 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d iew that are sim
16840 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e ulated by an [IN
16850 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
16860 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 ].** are not cou
16870 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c nted. Only real
16880 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 table changes a
16890 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a re counted..**.*
168a0 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 * ^(A "row chang
168b0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 e" is a change t
168c0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f o a single row o
168d0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 f a single table
168e0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e .** caused by an
168f0 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c INSERT, DELETE,
16900 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 or UPDATE state
16910 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 ment. Rows that
16920 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 .** are changed
16930 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 as side effects
16940 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e of [REPLACE] con
16950 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 straint resoluti
16960 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c on,.** rollback,
16970 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e ABORT processin
16980 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c g, [DROP TABLE],
16990 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 or by any other
169a0 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 .** mechanisms d
169b0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 o not count as d
169c0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 irect row change
169d0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 s.)^.**.** A "tr
169e0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 igger context" i
169f0 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 s a scope of exe
16a00 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 cution that begi
16a10 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 ns and.** ends w
16a20 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f ith the script o
16a30 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 f a [CREATE TRIG
16a40 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 GER | trigger].
16a50 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 .** Most SQL sta
16a60 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 tements are.** e
16a70 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 valuated outside
16a80 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e of any trigger.
16a90 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 This is the "t
16aa0 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 op level".** tri
16ab0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 gger context. I
16ac0 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 f a trigger fire
16ad0 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c s from the top l
16ae0 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 evel, a.** new t
16af0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 rigger context i
16b00 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 s entered for th
16b10 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 e duration of th
16b20 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 at one.** trigge
16b30 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 r. Subtriggers
16b40 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 create subcontex
16b50 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 ts for their dur
16b60 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 ation..**.** ^Ca
16b70 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
16b80 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 xec()] or [sqlit
16b90 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 e3_step()] recur
16ba0 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e sively does.** n
16bb0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 ot create a new
16bc0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e trigger context.
16bd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
16be0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
16bf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 e number of dire
16c00 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 ct row changes i
16c10 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 n the.** most re
16c20 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 cent INSERT, UPD
16c30 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 ATE, or DELETE s
16c40 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
16c50 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 the same.** trig
16c60 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
16c70 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 ** ^Thus, when c
16c80 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 alled from the t
16c90 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 op level, this f
16ca0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
16cb0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
16cc0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
16cd0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 most recent INSE
16ce0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
16cf0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c ELETE.** that al
16d00 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 so occurred at t
16d10 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e he top level. ^
16d20 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 (Within the body
16d30 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a of a trigger,.*
16d40 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 * the sqlite3_ch
16d50 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 anges() interfac
16d60 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
16d70 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
16d80 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 er of.** changes
16d90 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 in the most rec
16da0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
16db0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
16dc0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 or DELETE.** sta
16dd0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 tement within th
16de0 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 e body of the sa
16df0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 me trigger..** H
16e00 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 owever, the numb
16e10 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 er returned does
16e20 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 not include cha
16e30 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 nges.** caused b
16e40 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 y subtriggers si
16e50 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 nce those have t
16e60 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 heir own context
16e70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c .)^.**.** See al
16e80 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
16e90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
16ea0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a interface, the.
16eb0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 ** [count_change
16ec0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 s pragma], and t
16ed0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 he [changes() SQ
16ee0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
16ef0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
16f00 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 thread makes ch
16f10 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d anges on the sam
16f20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
16f30 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b ction.** while [
16f40 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
16f50 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
16f60 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
16f70 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 urned.** is unpr
16f80 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
16f90 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f t meaningful..*/
16fa0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
16fb0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
16fc0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
16fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 * CAPI3REF: Tota
16fe0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 l Number Of Rows
16ff0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 Modified.**.**
17000 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
17010 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
17020 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 r of row changes
17030 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 caused by [INSE
17040 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d RT],.** [UPDATE]
17050 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 or [DELETE] sta
17060 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 tements since th
17070 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
17080 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e ection] was open
17090 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 ed..** ^(The cou
170a0 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 nt returned by s
170b0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
170c0 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 nges() includes
170d0 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 all changes.** f
170e0 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 rom all [CREATE
170f0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 TRIGGER | trigge
17100 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 r] contexts and
17110 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a changes made by.
17120 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 ** [foreign key
17130 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 actions]. Howeve
17140 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 r,.** the count
17150 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
17160 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f changes used to
17170 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c implement [REPL
17180 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 ACE] constraints
17190 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b ,.** do rollback
171a0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 s or ABORT proce
171b0 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 ssing, or [DROP
171c0 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e TABLE] processin
171d0 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 g. The.** count
171e0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
171f0 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 e rows of views
17200 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e that fire an [IN
17210 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
17220 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 ],.** though if
17230 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 the INSTEAD OF t
17240 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 rigger makes cha
17250 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c nges of its own,
17260 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a those changes .
17270 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 ** are counted.)
17280 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ^.** ^The sqlite
17290 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
172a0 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 ) function count
172b0 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 s the changes as
172c0 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 soon as.** the
172d0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d statement that m
172e0 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d akes them is com
172f0 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 pleted (when the
17300 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c statement handl
17310 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 e.** is passed t
17320 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
17330 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
17340 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a finalize()])..**
17350 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
17360 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
17370 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
17380 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
17390 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
173a0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 nd the [total_ch
173b0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
173c0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
173d0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
173e0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
173f0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
17400 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
17410 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
17420 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
17430 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
17440 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 en the value.**
17450 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 returned is unpr
17460 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
17470 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f t meaningful..*/
17480 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
17490 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
174a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
174b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
174c0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
174d0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
174e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
174f0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 ction causes any
17500 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 pending databas
17510 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 e operation to a
17520 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 bort and.** retu
17530 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 rn at its earlie
17540 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 st opportunity.
17550 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
17560 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c typically.** cal
17570 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 led in response
17580 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e to a user action
17590 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e such as pressin
175a0 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 g "Cancel".** or
175b0 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 Ctrl-C where th
175c0 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c e user wants a l
175d0 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 ong query operat
175e0 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 ion to halt.** i
175f0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a mmediately..**.*
17600 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f * ^It is safe to
17610 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
17620 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 ne from a thread
17630 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
17640 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 the.** thread th
17650 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 at is currently
17660 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 running the data
17670 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 base operation.
17680 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f But it.** is no
17690 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 t safe to call t
176a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
176b0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
176c0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a nection] that.**
176d0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 is closed or mi
176e0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 ght close before
176f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
17700 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
17710 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f .** ^If an SQL o
17720 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 peration is very
17730 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 nearly finished
17740 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 at the time whe
17750 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 n.** sqlite3_int
17760 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c errupt() is call
17770 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 ed, then it migh
17780 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 t not have an op
17790 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 portunity.** to
177a0 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 be interrupted a
177b0 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 nd might continu
177c0 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e e to completion.
177d0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f .**.** ^An SQL o
177e0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 peration that is
177f0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c interrupted wil
17800 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
17810 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 _INTERRUPT]..**
17820 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 ^If the interrup
17830 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f ted SQL operatio
17840 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 n is an INSERT,
17850 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
17860 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 E.** that is ins
17870 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 ide an explicit
17880 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
17890 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 n the entire tra
178a0 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c nsaction.** will
178b0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
178c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a automatically..*
178d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
178e0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 3_interrupt(D) c
178f0 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 all is in effect
17900 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 until all curre
17910 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 ntly running.**
17920 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f SQL statements o
17930 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
17940 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 ection] D comple
17950 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 te. ^Any new SQ
17960 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
17970 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
17980 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
17990 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
179a0 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 all and before t
179b0 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 he .** running s
179c0 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 tatements reache
179d0 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 s zero are inter
179e0 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 rupted as if the
179f0 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 y had been.** ru
17a00 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 nning prior to t
17a10 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
17a20 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e rupt() call. ^N
17a30 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ew SQL statement
17a40 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
17a50 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
17a60 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e running statemen
17a70 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 t count reaches
17a80 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 zero are.** not
17a90 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 effected by the
17aa0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
17ab0 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 t()..** ^A call
17ac0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 to sqlite3_inter
17ad0 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 rupt(D) that occ
17ae0 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 urs when there a
17af0 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a re no running.**
17b00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
17b10 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 is a no-op and h
17b20 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 as no effect on
17b30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
17b40 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
17b50 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c ed after the sql
17b60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
17b70 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a call returns..*
17b80 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 *.** If the data
17b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
17ba0 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 closes while [sq
17bb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
17bc0 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 )].** is running
17bd0 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 then bad things
17be0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 will likely hap
17bf0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 pen..*/.SQLITE_A
17c00 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
17c10 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 interrupt(sqlite
17c20 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
17c30 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
17c40 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
17c50 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a ent Is Complete.
17c60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
17c70 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 ines are useful
17c80 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c during command-l
17c90 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 ine input to det
17ca0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a ermine if the.**
17cb0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 currently enter
17cc0 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f ed text seems to
17cd0 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 form a complete
17ce0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f SQL statement o
17cf0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e r.** if addition
17d00 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 al input is need
17d10 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e ed before sendin
17d20 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a g the text into.
17d30 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 ** SQLite for pa
17d40 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 rsing. ^These r
17d50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 outines return 1
17d60 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 if the input st
17d70 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 ring.** appears
17d80 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 to be a complete
17d90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
17da0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 ^A statement is
17db0 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a judged to be.**
17dc0 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 complete if it
17dd0 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 ends with a semi
17de0 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 colon token and
17df0 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 is not a prefix
17e00 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 of a.** well-for
17e10 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 med CREATE TRIGG
17e20 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e ER statement. ^
17e30 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 Semicolons that
17e40 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 are embedded wit
17e50 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 hin.** string li
17e60 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 terals or quoted
17e70 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 identifier name
17e80 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 s or comments ar
17e90 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e e not.** indepen
17ea0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 dent tokens (the
17eb0 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 y are part of th
17ec0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 e token in which
17ed0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 they are.** emb
17ee0 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 edded) and thus
17ef0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 do not count as
17f00 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d a statement term
17f10 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 inator. ^Whites
17f20 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d pace.** and comm
17f30 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 ents that follow
17f40 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 the final semic
17f50 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 olon are ignored
17f60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
17f70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 outines return 0
17f80 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e if the statemen
17f90 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e t is incomplete.
17fa0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 ^If a.** memor
17fb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
17fc0 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f ls, then SQLITE_
17fd0 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 NOMEM is returne
17fe0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 d..**.** ^These
17ff0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 routines do not
18000 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 parse the SQL st
18010 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a atements thus.**
18020 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 will not detect
18030 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 syntactically i
18040 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a ncorrect SQL..**
18050 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 .** ^(If SQLite
18060 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 has not been ini
18070 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b tialized using [
18080 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
18090 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 ze()] prior .**
180a0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 to invoking sqli
180b0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
180c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e then sqlite3_in
180d0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
180e0 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 voked.** automat
180f0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 ically by sqlite
18100 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 3_complete16().
18110 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c If that initial
18120 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a ization fails,.*
18130 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 * then the retur
18140 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c n value from sql
18150 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
18160 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 ) will be non-ze
18170 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 ro.** regardless
18180 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
18190 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c ot the input SQL
181a0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a is complete.)^.
181b0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
181c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
181d0 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 lete()] must be
181e0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
181f0 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e d.** UTF-8 strin
18200 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 g..**.** The inp
18210 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
18220 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 omplete16()] mus
18230 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
18240 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
18250 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 string in nativ
18260 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f e byte order..*/
18270 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
18280 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
18290 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c (const char *sql
182a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
182b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
182c0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 te16(const void
182d0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 *sql);../*.** CA
182e0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
182f0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 A Callback To H
18300 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 andle SQLITE_BUS
18310 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e Y Errors.**.** ^
18320 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
18330 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
18340 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 ction that might
18350 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
18360 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d ever.** an attem
18370 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 pt is made to op
18380 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 en a database ta
18390 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 ble that another
183a0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 thread.** or pr
183b0 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 ocess has locked
183c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
183d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 busy callback is
183e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c NULL, then [SQL
183f0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
18400 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
18410 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ED].** is return
18420 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 ed immediately u
18430 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 pon encountering
18440 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 the lock. ^If
18450 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
18460 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c k.** is not NULL
18470 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 , then the callb
18480 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 ack might be inv
18490 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 oked with two ar
184a0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e guments..**.** ^
184b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
184c0 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 nt to the busy h
184d0 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 andler is a copy
184e0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f of the void* po
184f0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 inter which.** i
18500 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 s the third argu
18510 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
18520 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 busy_handler().
18530 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 ^The second arg
18540 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 ument to.** the
18550 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c busy handler cal
18560 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d lback is the num
18570 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 ber of times tha
18580 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c t the busy handl
18590 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 er has.** been i
185a0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 nvoked for this
185b0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 locking event.
185c0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 ^If the.** busy
185d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
185e0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 0, then no addi
185f0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 tional attempts
18600 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 are made to.** a
18610 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
18620 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 se and [SQLITE_B
18630 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
18640 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 IOERR_BLOCKED] i
18650 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e s returned..** ^
18660 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
18670 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
18680 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 , then another a
18690 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 ttempt.** is mad
186a0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 e to open the da
186b0 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 tabase for readi
186c0 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 ng and the cycle
186d0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 repeats..**.**
186e0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 The presence of
186f0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 a busy handler d
18700 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 oes not guarante
18710 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 e that it will b
18720 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 e invoked.** whe
18730 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 n there is lock
18740 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 contention. ^If
18750 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
18760 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 s that invoking
18770 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 the busy.** hand
18780 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
18790 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 in a deadlock,
187a0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 it will go ahead
187b0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
187c0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 ITE_BUSY].** or
187d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
187e0 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f OCKED] instead o
187f0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 f invoking the b
18800 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 usy handler..**
18810 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 Consider a scena
18820 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 rio where one pr
18830 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 ocess is holding
18840 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 a read lock tha
18850 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e t.** it is tryin
18860 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 g to promote to
18870 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
18880 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 and.** a second
18890 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
188a0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f ng a reserved lo
188b0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 ck that it is tr
188c0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f ying.** to promo
188d0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 te to an exclusi
188e0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 ve lock. The fi
188f0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e rst process cann
18900 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 ot proceed.** be
18910 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
18920 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e ked by the secon
18930 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 d and the second
18940 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a process cannot.
18950 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 ** proceed becau
18960 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
18970 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 by the first.
18980 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 If both processe
18990 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 s.** invoke the
189a0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e busy handlers, n
189b0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 either will make
189c0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 any progress.
189d0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 Therefore,.** SQ
189e0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 Lite returns [SQ
189f0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 LITE_BUSY] for t
18a00 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
18a10 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 , hoping that th
18a20 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 is.** will induc
18a30 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 e the first proc
18a40 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 ess to release i
18a50 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 ts read lock and
18a60 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 allow.** the se
18a70 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 cond process to
18a80 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e proceed..**.** ^
18a90 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 The default busy
18aa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c callback is NUL
18ab0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 L..**.** ^The [S
18ac0 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f QLITE_BUSY] erro
18ad0 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 r is converted t
18ae0 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f o [SQLITE_IOERR_
18af0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e BLOCKED].** when
18b00 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 SQLite is in th
18b10 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 e middle of a la
18b20 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 rge transaction
18b30 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a where all the.**
18b40 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f changes will no
18b50 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 t fit into the i
18b60 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 n-memory cache.
18b70 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 SQLite will.**
18b80 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 already hold a R
18b90 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 ESERVED lock on
18ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
18bb0 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a e, but it needs.
18bc0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 ** to promote th
18bd0 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 is lock to EXCLU
18be0 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 SIVE so that it
18bf0 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a can spill cache.
18c00 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 ** pages into th
18c10 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
18c20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 without harm to
18c30 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 concurrent.** re
18c40 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 aders. ^If it i
18c50 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d s unable to prom
18c60 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 ote the lock, th
18c70 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 en the in-memory
18c80 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 .** cache will b
18c90 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 e left in an inc
18ca0 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 onsistent state
18cb0 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 and so the error
18cc0 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d .** code is prom
18cd0 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 oted from the re
18ce0 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 latively benign
18cf0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f [SQLITE_BUSY] to
18d00 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 .** the more sev
18d10 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 ere [SQLITE_IOER
18d20 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 R_BLOCKED]. ^Th
18d30 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 is error code pr
18d40 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 omotion.** force
18d50 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 s an automatic r
18d60 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 ollback of the c
18d70 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 hanges. See the
18d80 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 .** <a href="/cv
18d90 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 strac/wiki?p=Cor
18da0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 ruptionFollowing
18db0 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 BusyError">.** C
18dc0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 orruptionFollowi
18dd0 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 ngBusyError</a>
18de0 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 wiki page for a
18df0 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 discussion of wh
18e00 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 y.** this is imp
18e10 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ortant..**.** ^(
18e20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
18e30 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
18e40 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 handler defined
18e50 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 for each.** [dat
18e60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18e70 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 ]. Setting a ne
18e80 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 w busy handler c
18e90 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 lears any.** pre
18ea0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 viously set hand
18eb0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 ler.)^ ^Note th
18ec0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
18ed0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
18ee0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f ()].** will also
18ef0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 set or clear th
18f00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
18f10 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 **.** The busy c
18f20 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e allback should n
18f30 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 ot take any acti
18f40 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 ons which modify
18f50 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
18f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
18f70 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
18f80 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 y handler. Any
18f90 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
18fa0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
18fb0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
18fc0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 .** A busy hand
18fd0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ler must not clo
18fe0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
18ff0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 connection.** or
19000 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
19010 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b ment] that invok
19020 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
19030 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ler..*/.SQLITE_A
19040 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
19050 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 usy_handler(sqli
19060 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 te3*, int(*)(voi
19070 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b d*,int), void*);
19080 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
19090 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d : Set A Busy Tim
190a0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 eout.**.** ^This
190b0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
190c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
190d0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e ndler | busy han
190e0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 dler] that sleep
190f0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 s.** for a speci
19100 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 fied amount of t
19110 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 ime when a table
19120 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 is locked. ^Th
19130 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c e handler.** wil
19140 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 l sleep multiple
19150 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 times until at
19160 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
19170 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
19180 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 ing.** have accu
19190 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 mulated. ^After
191a0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
191b0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
191c0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 leeping,.** the
191d0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 handler returns
191e0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 0 which causes [
191f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
19200 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 to return.** [SQ
19210 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 LITE_BUSY] or [S
19220 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
19230 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c KED]..**.** ^Cal
19240 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e ling this routin
19250 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 e with an argume
19260 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 nt less than or
19270 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a equal to zero.**
19280 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 turns off all b
19290 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a usy handlers..**
192a0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 .** ^(There can
192b0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 only be a single
192c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f busy handler fo
192d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a r a particular.*
192e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
192f0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 ection] any any
19300 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 given moment. I
19310 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 f another busy h
19320 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 andler.** was de
19330 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 fined (using [s
19340 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
19350 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f ler()]) prior to
19360 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 calling.** this
19370 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f routine, that o
19380 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 ther busy handle
19390 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a r is cleared.)^.
193a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
193b0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 t sqlite3_busy_t
193c0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c imeout(sqlite3*,
193d0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a int ms);../*.**
193e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 CAPI3REF: Conve
193f0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 nience Routines
19400 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 For Running Quer
19410 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ies.**.** This i
19420 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 s a legacy inter
19430 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 face that is pre
19440 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 served for backw
19450 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
19460 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 ty..** Use of th
19470 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
19480 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e not recommended.
19490 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f .**.** Definitio
194a0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 n: A <b>result t
194b0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f able</b> is memo
194c0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ry data structur
194d0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 e created by the
194e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
194f0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 _table()] interf
19500 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 ace. A result t
19510 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 able records the
19520 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 .** complete que
19530 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 ry results from
19540 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 one or more quer
19550 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ies..**.** The t
19560 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c able conceptuall
19570 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f y has a number o
19580 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d f rows and colum
19590 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 ns. But.** thes
195a0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f e numbers are no
195b0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 t part of the re
195c0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c sult table itsel
195d0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d f. These.** num
195e0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 bers are obtaine
195f0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c d separately. L
19600 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 et N be the numb
19610 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e er of rows.** an
19620 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 d M be the numbe
19630 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a r of columns..**
19640 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
19650 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f le is an array o
19660 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 f pointers to ze
19670 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
19680 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 F-8 strings..**
19690 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a There are (N+1)*
196a0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 M elements in th
196b0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 e array. The fi
196c0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 rst M pointers p
196d0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d oint.** to zero-
196e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
196f0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e gs that contain
19700 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 the names of th
19710 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 e columns..** Th
19720 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 e remaining entr
19730 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f ies all point to
19740 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 query results.
19750 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 NULL values res
19760 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 ult.** in NULL p
19770 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 ointers. All ot
19780 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 her values are i
19790 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 n their UTF-8 ze
197a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
197b0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e string represen
197c0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e tation as return
197d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
197e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
197f0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
19800 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 ble might consis
19810 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 t of one or more
19820 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
19830 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ons..** It is no
19840 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 t safe to pass a
19850 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 result table di
19860 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 rectly to [sqlit
19870 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 e3_free()]..** A
19880 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 result table sh
19890 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 ould be dealloca
198a0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
198b0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
198c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 ..**.** ^(As an
198d0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 example of the r
198e0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d esult table form
198f0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 at, suppose a qu
19900 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ery result.** is
19910 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
19920 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
19930 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e pre>.** N
19940 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 ame | Age
19950 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d .** -----
19960 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
19970 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 --.** Ali
19980 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a ce | 43.**
19990 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 Bob
199a0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 | 28.**
199b0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c Cindy |
199c0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 21.** </pre></b
199d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
199e0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 There are two c
199f0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 olumn (M==2) and
19a00 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d three rows (N==
19a10 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 3). Thus the.**
19a20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 result table ha
19a30 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 s 8 entries. Su
19a40 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 ppose the result
19a50 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 table is stored
19a60 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 .** in an array
19a70 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 names azResult.
19a80 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 Then azResult h
19a90 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e olds this conten
19aa0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 t:.**.** <blockq
19ab0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
19ac0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
19ad0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 1;0] = "Name";.*
19ae0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
19af0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 t[1] = "Age"
19b00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
19b10 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 sult[2] = "A
19b20 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 lice";.**
19b30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d azResult[3]
19b40 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 = "43";.**
19b50 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
19b60 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 4] = "Bob";.**
19b70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
19b80 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 91;5] = "28";.**
19b90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
19ba0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 [6] = "Cindy
19bb0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
19bc0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 esult[7] = "
19bd0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 21";.** </pre></
19be0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
19bf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
19c00 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e _get_table() fun
19c10 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 ction evaluates
19c20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 one or more.** s
19c30 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
19c40 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
19c50 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 s in the zero-te
19c60 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a rminated UTF-8.*
19c70 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 * string of its
19c80 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 2nd parameter an
19c90 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 d returns a resu
19ca0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a lt table to the.
19cb0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e ** pointer given
19cc0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 in its 3rd para
19cd0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 meter..**.** Aft
19ce0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
19cf0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 on has finished
19d00 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 with the result
19d10 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 from sqlite3_get
19d20 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 _table(),.** it
19d30 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 must pass the re
19d40 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 sult table point
19d50 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 er to sqlite3_fr
19d60 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 ee_table() in or
19d70 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 der to.** releas
19d80 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
19d90 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 t was malloced.
19da0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
19db0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 way the.** [sqli
19dc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 te3_malloc()] ha
19dd0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c ppens within sql
19de0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
19df0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a , the calling.**
19e00 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
19e10 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b ot try to call [
19e20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
19e30 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a directly. Only.
19e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
19e50 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c _table()] is abl
19e60 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 e to release the
19e70 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 memory properly
19e80 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a and safely..**.
19e90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
19ea0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 et_table() inter
19eb0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
19ec0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 ted as a wrapper
19ed0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 around.** [sqli
19ee0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 te3_exec()]. Th
19ef0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
19f00 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f ble() routine do
19f10 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 es not have acce
19f20 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 ss.** to any int
19f30 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 ernal data struc
19f40 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e tures of SQLite.
19f50 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 It uses only t
19f60 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 he public.** int
19f70 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 erface defined h
19f80 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 ere. As a conse
19f90 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 quence, errors t
19fa0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 hat occur in the
19fb0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 .** wrapper laye
19fc0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 r outside of the
19fd0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 internal [sqlit
19fe0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 e3_exec()] call
19ff0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 are not.** refle
1a000 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 cted in subseque
1a010 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
1a020 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
1a030 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 or.** [sqlite3_e
1a040 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c rrmsg()]..*/.SQL
1a050 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1a060 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
1a070 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1a080 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
1a090 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
1a0a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
1a0b0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 , /* SQL to
1a0c0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
1a0d0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 char ***pazRes
1a0e0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c ult, /* Resul
1a0f0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 ts of the query
1a100 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c */. int *pnRow,
1a110 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
1a120 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
1a130 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
1a140 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c */. int *pnCol
1a150 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e umn, /* N
1a160 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
1a170 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 columns written
1a180 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a here */. char *
1a190 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 *pzErrmsg
1a1a0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
1a1b0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
1a1c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
1a1d0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1a1e0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 le(char **result
1a1f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1a200 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 EF: Formatted St
1a210 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 ring Printing Fu
1a220 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
1a230 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1a240 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 work-alikes of
1a250 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 the "printf()" f
1a260 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f amily of functio
1a270 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 ns.** from the s
1a280 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
1a290 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 y..**.** ^The sq
1a2a0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 lite3_mprintf()
1a2b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 and sqlite3_vmpr
1a2c0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 intf() routines
1a2d0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 write their.** r
1a2e0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f esults into memo
1a2f0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
1a300 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1a310 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 ()]..** The stri
1a320 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
1a330 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e these two routin
1a340 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 es should be.**
1a350 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c released by [sql
1a360 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e ite3_free()]. ^
1a370 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 Both routines re
1a380 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 turn a.** NULL p
1a390 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 ointer if [sqlit
1a3a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 e3_malloc()] is
1a3b0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
1a3c0 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d te enough.** mem
1a3d0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
1a3e0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
1a3f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
1a400 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1a410 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 routine is simi
1a420 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 lar to "snprintf
1a430 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ()" from.** the
1a440 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
1a450 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 ry. The result
1a460 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 is written into
1a470 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 the.** buffer su
1a480 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 pplied as the se
1a490 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 cond parameter w
1a4a0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 hose size is giv
1a4b0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 en by.** the fir
1a4c0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f st parameter. No
1a4d0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 te that the orde
1a4e0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 r of the.** firs
1a4f0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 t two parameters
1a500 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f is reversed fro
1a510 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 m snprintf().)^
1a520 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 This is an.** h
1a530 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 istorical accide
1a540 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 nt that cannot b
1a550 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 e fixed without
1a560 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b breaking.** back
1a570 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
1a580 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 ity. ^(Note als
1a590 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 o that sqlite3_s
1a5a0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 nprintf().** ret
1a5b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1a5c0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 o its buffer ins
1a5d0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 tead of the numb
1a5e0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 er of.** charact
1a5f0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 ers actually wri
1a600 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 tten into the bu
1a610 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 ffer.)^ We admi
1a620 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 t that.** the nu
1a630 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
1a640 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 rs written would
1a650 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 be a more usefu
1a660 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 l return.** valu
1a670 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 e but we cannot
1a680 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 change the imple
1a690 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
1a6a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1a6b0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 ** now without b
1a6c0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 reaking compatib
1a6d0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 ility..**.** ^As
1a6e0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 long as the buf
1a6f0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 fer size is grea
1a700 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 ter than zero, s
1a710 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1a720 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 ).** guarantees
1a730 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 that the buffer
1a740 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 is always zero-t
1a750 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 erminated. ^The
1a760 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
1a770 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
1a780 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
1a790 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
1a7a0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
1a7b0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
1a7c0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
1a7d0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
1a7e0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
1a7f0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
1a800 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
1a810 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ters..**.** ^The
1a820 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e sqlite3_vsnprin
1a830 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
1a840 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f a varargs versio
1a850 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 n of sqlite3_snp
1a860 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 rintf()..**.** T
1a870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c hese routines al
1a880 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 l implement some
1a890 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d additional form
1a8a0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e atting.** option
1a8b0 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 s that are usefu
1a8c0 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 l for constructi
1a8d0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ng SQL statement
1a8e0 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 s..** All of the
1a8f0 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 usual printf()
1a900 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1a910 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 ns apply. In ad
1a920 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a dition, there.**
1a930 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 is are "%q", "%
1a940 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 Q", and "%z" opt
1a950 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ions..**.** ^(Th
1a960 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %q option work
1a970 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 s like %s in tha
1a980 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 t it substitutes
1a990 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 a nul-terminate
1a9a0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d d.** string from
1a9b0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 the argument li
1a9c0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f st. But %q also
1a9d0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 doubles every '
1a9e0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a \'' character..*
1a9f0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 * %q is designed
1aa00 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 for use inside
1aa10 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
1aa20 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 .)^ By doubling
1aa30 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 each '\''.** ch
1aa40 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 aracter it escap
1aa50 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 es that characte
1aa60 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 r and allows it
1aa70 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 to be inserted i
1aa80 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e nto.** the strin
1aa90 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 g..**.** For exa
1aaa0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 mple, assume the
1aab0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 string variable
1aac0 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 zText contains
1aad0 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a text as follows:
1aae0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1aaf0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
1ab00 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 r *zText = "It's
1ab10 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a a happy day!";.
1ab20 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1ab30 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 quote>.**.** One
1ab40 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 can use this te
1ab50 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 xt in an SQL sta
1ab60 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 tement as follow
1ab70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1ab80 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
1ab90 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
1aba0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
1abb0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
1abc0 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 ALUES('%q')", zT
1abd0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
1abe0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
1abf0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
1ac00 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
1ac10 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1ac20 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1ac30 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 Because the %q f
1ac40 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 ormat string is
1ac50 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 used, the '\'' c
1ac60 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 haracter in zTex
1ac70 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 t.** is escaped
1ac80 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 and the SQL gene
1ac90 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c rated is as foll
1aca0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1acb0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1acc0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
1acd0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 le1 VALUES('It''
1ace0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
1acf0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1ad00 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1ad10 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 is is correct.
1ad20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 Had we used %s i
1ad30 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 nstead of %q, th
1ad40 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a e generated SQL.
1ad50 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f ** would have lo
1ad60 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a oked like this:.
1ad70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1ad80 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
1ad90 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
1ada0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 ALUES('It's a ha
1adb0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c ppy day!');.** <
1adc0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1add0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 e>.**.** This se
1ade0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 cond example is
1adf0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 an SQL syntax er
1ae00 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 ror. As a gener
1ae10 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 al rule you shou
1ae20 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 ld.** always use
1ae30 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %q instead of %
1ae40 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 s when inserting
1ae50 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 text into a str
1ae60 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a ing literal..**.
1ae70 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 ** ^(The %Q opti
1ae80 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 on works like %q
1ae90 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 except it also
1aea0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 adds single quot
1aeb0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 es around.** the
1aec0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
1aed0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 total string. A
1aee0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 dditionally, if
1aef0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e the parameter in
1af00 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 the.** argument
1af10 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 list is a NULL
1af20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 pointer, %Q subs
1af30 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 titutes the text
1af40 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 "NULL" (without
1af50 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 .** single quote
1af60 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 s).)^ So, for e
1af70 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
1af80 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
1af90 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1afa0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
1afb0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1afc0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
1afd0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
1afe0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
1aff0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
1b000 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
1b010 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
1b020 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
1b030 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1b040 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
1b050 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
1b060 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
1b070 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
1b080 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
1b090 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
1b0a0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
1b0b0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1b0c0 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d ^(The "%z" form
1b0d0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f atting option wo
1b0e0 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 rks like "%s" bu
1b0f0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 t with the.** ad
1b100 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 dition that afte
1b110 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 r the string has
1b120 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 been read and c
1b130 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 opied into.** th
1b140 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 e result, [sqlit
1b150 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 e3_free()] is ca
1b160 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 lled on the inpu
1b170 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 t string.)^.*/.S
1b180 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a QLITE_API char *
1b190 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1b1a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 const char*,...)
1b1b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
1b1c0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 r *sqlite3_vmpri
1b1d0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
1b1e0 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 va_list);.SQLIT
1b1f0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 E_API char *sqli
1b200 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 te3_snprintf(int
1b210 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 ,char*,const cha
1b220 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 r*, ...);.SQLITE
1b230 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 _API char *sqlit
1b240 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 e3_vsnprintf(int
1b250 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 ,char*,const cha
1b260 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f r*, va_list);../
1b270 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
1b280 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
1b290 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a Subsystem.**.**
1b2a0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
1b2b0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 uses these thre
1b2c0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 e routines for a
1b2d0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a ll of its own.**
1b2e0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 internal memory
1b2f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
1b300 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 s. "Core" in the
1b310 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e previous senten
1b320 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 ce.** does not i
1b330 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 nclude operating
1b340 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 -system specific
1b350 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
1b360 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e ion. The.** Win
1b370 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 dows VFS uses na
1b380 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e tive malloc() an
1b390 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d d free() for som
1b3a0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a e operations..**
1b3b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1b3c0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e _malloc() routin
1b3d0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
1b3e0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a ter to a block.*
1b3f0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c * of memory at l
1b400 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
1b410 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 length, where N
1b420 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 is the parameter
1b430 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
1b440 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 _malloc() is una
1b450 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 ble to obtain su
1b460 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a fficient free.**
1b470 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 memory, it retu
1b480 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
1b490 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 er. ^If the par
1b4a0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 ameter N to.** s
1b4b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1b4c0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 is zero or negat
1b4d0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ive then sqlite3
1b4e0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e _malloc() return
1b4f0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
1b500 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c ter..**.** ^Call
1b510 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ing sqlite3_free
1b520 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 () with a pointe
1b530 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 r previously ret
1b540 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
1b550 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 te3_malloc() or
1b560 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1b570 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 ) releases that
1b580 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 memory so.** tha
1b590 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 t it might be re
1b5a0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 used. ^The sqli
1b5b0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 te3_free() routi
1b5c0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 ne is.** a no-op
1b5d0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 if is called wi
1b5e0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
1b5f0 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 r. Passing a NU
1b600 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f LL pointer.** to
1b610 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1b620 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 is harmless. Af
1b630 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c ter being freed,
1b640 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c memory.** shoul
1b650 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 d neither be rea
1b660 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 d nor written.
1b670 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 Even reading pre
1b680 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a viously freed.**
1b690 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 memory might re
1b6a0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e sult in a segmen
1b6b0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 tation fault or
1b6c0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 other severe err
1b6d0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f or..** Memory co
1b6e0 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d rruption, a segm
1b6f0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 entation fault,
1b700 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
1b710 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 error.** might r
1b720 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 esult if sqlite3
1b730 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 _free() is calle
1b740 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c d with a non-NUL
1b750 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a L pointer that.*
1b760 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e * was not obtain
1b770 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
1b780 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 malloc() or sqli
1b790 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
1b7a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 *.** ^(The sqlit
1b7b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 e3_realloc() int
1b7c0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
1b7d0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 to resize a.** p
1b7e0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rior memory allo
1b7f0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 cation to be at
1b800 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 least N bytes, w
1b810 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a here N is the.**
1b820 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1b830 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 r. The memory a
1b840 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
1b850 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 resized is the f
1b860 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
1b870 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 r.)^ ^ If the fi
1b880 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
1b890 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1b8a0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 ().** is a NULL
1b8b0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
1b8c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
1b8d0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
1b8e0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
1b8f0 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 loc(N) where N i
1b900 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
1b910 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1b920 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
1b930 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 ^If the second p
1b940 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1b950 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 te3_realloc() is
1b960 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 zero or.** nega
1b970 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 tive then the be
1b980 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c havior is exactl
1b990 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 y the same as ca
1b9a0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
1b9b0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 _free(P) where P
1b9c0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
1b9d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
1b9e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
1b9f0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f ^sqlite3_reallo
1ba00 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f c() returns a po
1ba10 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 inter to a memor
1ba20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
1ba30 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
1ba40 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e tes in size or N
1ba50 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e ULL if sufficien
1ba60 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 t memory is unav
1ba70 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 ailable..** ^If
1ba80 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 M is the size of
1ba90 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
1baa0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 ation, then min(
1bab0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 N,M) bytes.** of
1bac0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
1bad0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 ation are copied
1bae0 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e into the beginn
1baf0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 ing of buffer re
1bb00 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
1bb10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 ite3_realloc() a
1bb20 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c nd the prior all
1bb30 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 ocation is freed
1bb40 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
1bb50 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
1bb60 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ns NULL, then th
1bb70 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1bb80 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 on.** is not fre
1bb90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d ed..**.** ^The m
1bba0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
1bbb0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
1bbc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
1bbd0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 ealloc().** is a
1bbe0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
1bbf0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
1bc00 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 yte boundary, or
1bc10 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 to a.** 4 byte
1bc20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 boundary if the
1bc30 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 [SQLITE_4_BYTE_A
1bc40 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 LIGNED_MALLOC] c
1bc50 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
1bc60 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a ption is used..*
1bc70 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
1bc80 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
1bc90 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
1bca0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
1bcb0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
1bcc0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
1bcd0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
1bce0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
1bcf0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
1bd00 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
1bd10 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
1bd20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
1bd30 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
1bd40 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
1bd50 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
1bd60 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
1bd70 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
1bd80 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
1bd90 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
1bda0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 3.7.10, the Wind
1bdb0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
1bdc0 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a layer called.**
1bdd0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c the system mall
1bde0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1bdf0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f directly when co
1be00 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 nverting.** file
1be10 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 names between th
1be20 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 e UTF-8 encoding
1be30 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a used by SQLite.
1be40 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 ** and whatever
1be50 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e filename encodin
1be60 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 g is used by the
1be70 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 particular Wind
1be80 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 ows.** installat
1be90 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c ion. Memory all
1bea0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 ocation errors w
1beb0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 ere detected, bu
1bec0 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 t.** they were r
1bed0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
1bee0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
1bef0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
1bf00 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
1bf10 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
1bf20 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 ]..**.** The poi
1bf30 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
1bf40 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
1bf50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1bf60 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 realloc()].** mu
1bf70 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c st be either NUL
1bf80 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 L or else pointe
1bf90 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d rs obtained from
1bfa0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f a prior.** invo
1bfb0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
1bfc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
1bfd0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1bfe0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
1bff0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
1c000 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 leased..**.** Th
1c010 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
1c020 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 st not read or w
1c030 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 rite any part of
1c040 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d .** a block of m
1c050 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 emory after it h
1c060 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 as been released
1c070 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
1c080 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
1c090 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1c0a0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
1c0b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d void *sqlite3_m
1c0c0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 alloc(int);.SQLI
1c0d0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
1c0e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 ite3_realloc(voi
1c0f0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 d*, int);.SQLITE
1c100 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
1c110 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 3_free(void*);..
1c120 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1c130 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 Memory Allocator
1c140 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a Statistics.**.*
1c150 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 * SQLite provide
1c160 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 s these two inte
1c170 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 rfaces for repor
1c180 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 ting on the stat
1c190 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 us.** of the [sq
1c1a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
1c1b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1c1c0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
1c1d0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f realloc()].** ro
1c1e0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f utines, which fo
1c1f0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 rm the built-in
1c200 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1c210 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a n subsystem..**.
1c220 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
1c230 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
1c240 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
1c250 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
1c260 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 tes.** of memory
1c270 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 currently outst
1c280 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 anding (malloced
1c290 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e but not freed).
1c2a0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
1c2b0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1c2c0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 er()] routine re
1c2d0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 turns the maximu
1c2e0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 m.** value of [s
1c2f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1c300 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 ed()] since the
1c310 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
1c320 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 ** was last rese
1c330 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 t. ^The values
1c340 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
1c350 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
1c360 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 ()] and.** [sqli
1c370 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1c380 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 ater()] include
1c390 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 any overhead.**
1c3a0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 added by SQLite
1c3b0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 in its implement
1c3c0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
1c3d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 3_malloc()],.**
1c3e0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 but not overhead
1c3f0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e added by the an
1c400 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 y underlying sys
1c410 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 tem library.** r
1c420 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 outines that [sq
1c430 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
1c440 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 may call..**.**
1c450 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 ^The memory high
1c460 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 -water mark is r
1c470 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 eset to the curr
1c480 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 ent value of.**
1c490 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1c4a0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f used()] if and o
1c4b0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d nly if the param
1c4c0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 eter to.** [sqli
1c4d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1c4e0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e ater()] is true.
1c4f0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 ^The value ret
1c500 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c urned.** by [sql
1c510 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
1c520 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 water(1)] is the
1c530 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
1c540 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 .** prior to the
1c550 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 reset..*/.SQLIT
1c560 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
1c570 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
1c580 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 ry_used(void);.S
1c590 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
1c5a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
1c5b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1c5c0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b (int resetFlag);
1c5d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1c5e0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 : Pseudo-Random
1c5f0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 Number Generator
1c600 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f .**.** SQLite co
1c610 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 ntains a high-qu
1c620 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e ality pseudo-ran
1c630 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 dom number gener
1c640 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 ator (PRNG) used
1c650 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 to.** select ra
1c660 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f ndom [ROWID | RO
1c670 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 WIDs] when inser
1c680 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 ting new records
1c690 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 into a table th
1c6a0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 at.** already us
1c6b0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 es the largest p
1c6c0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e ossible [ROWID].
1c6d0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c The PRNG is al
1c6e0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 so used for.** t
1c6f0 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 he build-in rand
1c700 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 om() and randomb
1c710 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 lob() SQL functi
1c720 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 ons. This inter
1c730 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 face allows.** a
1c740 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 pplications to a
1c750 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 ccess the same P
1c760 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 RNG for other pu
1c770 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 rposes..**.** ^A
1c780 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f call to this ro
1c790 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 utine stores N b
1c7a0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
1c7b0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 ss into buffer P
1c7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
1c7d0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 st time this rou
1c7e0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 tine is invoked
1c7f0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c (either internal
1c800 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 ly or by.** the
1c810 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 application) the
1c820 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 PRNG is seeded
1c830 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 using randomness
1c840 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
1c850 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
1c860 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
1c870 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
1c880 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
1c890 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 ^On all subsequ
1c8a0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c ent invocations,
1c8b0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 the pseudo-rand
1c8c0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 omness is genera
1c8d0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c ted.** internall
1c8e0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 y and without re
1c8f0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 course to the [s
1c900 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e qlite3_vfs] xRan
1c910 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f domness.** metho
1c920 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 d..*/.SQLITE_API
1c930 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 void sqlite3_ra
1c940 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 ndomness(int N,
1c950 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a void *P);../*.**
1c960 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
1c970 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a le-Time Authoriz
1c980 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a ation Callbacks.
1c990 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
1c9a0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e ine registers an
1c9b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1c9c0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
1c9d0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
1c9e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
1c9f0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
1ca00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
1ca10 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 .** ^The authori
1ca20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1ca30 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
1ca40 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 tatements are be
1ca50 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 ing compiled.**
1ca60 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 by [sqlite3_prep
1ca70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
1ca80 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f riants [sqlite3_
1ca90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a prepare_v2()],.*
1caa0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1cab0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c re16()] and [sql
1cac0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1cad0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 2()]. ^At vario
1cae0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 us.** points dur
1caf0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 ing the compilat
1cb00 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 ion process, as
1cb10 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 logic is being c
1cb20 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 reated.** to per
1cb30 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 form various act
1cb40 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 ions, the author
1cb50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1cb60 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 invoked to.** s
1cb70 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 ee if those acti
1cb80 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ons are allowed.
1cb90 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ^The authorize
1cba0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c r callback shoul
1cbb0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
1cbc0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 ITE_OK] to allow
1cbd0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 the action, [SQ
1cbe0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 LITE_IGNORE] to
1cbf0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 disallow the.**
1cc00 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 specific action
1cc10 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 but allow the SQ
1cc20 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 L statement to c
1cc30 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a ontinue to be.**
1cc40 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 compiled, or [S
1cc50 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 QLITE_DENY] to c
1cc60 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 ause the entire
1cc70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
1cc80 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 be.** rejected
1cc90 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
1cca0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a ^If the authoriz
1ccb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
1ccc0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 rns.** any value
1ccd0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
1cce0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 ITE_IGNORE], [SQ
1ccf0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 LITE_OK], or [SQ
1cd00 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 LITE_DENY].** th
1cd10 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f en the [sqlite3_
1cd20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1cd30 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
1cd40 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a that triggered.
1cd50 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
1cd60 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
1cd70 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
1cd80 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
1cd90 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
1cda0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
1cdb0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f that means the o
1cdc0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 peration.** requ
1cdd0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 ested is ok. ^W
1cde0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
1cdf0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1ce00 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b _DENY], the.** [
1ce10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1ce20 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
1ce30 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
1ce40 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 iggered the.** a
1ce50 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
1ce60 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
1ce70 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 r message explai
1ce80 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 ning that.** acc
1ce90 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a ess is denied. .
1cea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
1ceb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1cec0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1ced0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
1cee0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 of the third.**
1cef0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1cf00 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
1cf10 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 horizer() interf
1cf20 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ace. ^The second
1cf30 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
1cf40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
1cf50 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
1cf60 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
1cf70 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
1cf80 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
1cf90 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
1cfa0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
1cfb0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 . ^The third thr
1cfc0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d ough sixth param
1cfd0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 eters.** to the
1cfe0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 callback are zer
1cff0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
1d000 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
1d010 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 n additional.**
1d020 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
1d030 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
1d040 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
1d050 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
1d060 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
1d070 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
1d080 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1d090 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
1d0a0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
1d0b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1d0c0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
1d0d0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
1d0e0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
1d0f0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
1d100 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
1d110 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
1d120 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
1d130 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
1d140 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
1d150 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
1d160 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
1d170 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
1d180 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
1d190 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
1d1a0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
1d1b0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
1d1c0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 table..** ^If th
1d1d0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
1d1e0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
1d1f0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
1d200 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 k returns.** [SQ
1d210 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
1d220 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f n the [DELETE] o
1d230 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
1d240 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 s but the.** [tr
1d250 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 uncate optimizat
1d260 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 ion] is disabled
1d270 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 and all rows ar
1d280 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 e deleted indivi
1d290 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e dually..**.** An
1d2a0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
1d2b0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 sed when [sqlite
1d2c0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
1d2d0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 aring].** SQL st
1d2e0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
1d2f0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
1d300 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 e, to ensure tha
1d310 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
1d320 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 ents.** do not t
1d330 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
1d340 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 a they are not a
1d350 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f llowed to see, o
1d360 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e r that they do n
1d370 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 ot.** try to exe
1d380 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 cute malicious s
1d390 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 tatements that d
1d3a0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 amage the databa
1d3b0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d se. For.** exam
1d3c0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
1d3d0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 ion may allow a
1d3e0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 user to enter ar
1d3f0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 bitrary.** SQL q
1d400 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 ueries for evalu
1d410 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 ation by a datab
1d420 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 ase. But the ap
1d430 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a plication does.*
1d440 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 * not want the u
1d450 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 ser to be able t
1d460 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 o make arbitrary
1d470 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a changes to the.
1d480 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e ** database. An
1d490 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c authorizer coul
1d4a0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e d then be put in
1d4b0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 place while the
1d4c0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 .** user-entered
1d4d0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 SQL is being [s
1d4e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
1d4f0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a prepared] that.
1d500 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 ** disallows eve
1d510 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b rything except [
1d520 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1d530 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ts..**.** Applic
1d540 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 ations that need
1d550 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
1d560 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 from untrusted s
1d570 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 ources.** might
1d580 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f also consider lo
1d590 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 wering resource
1d5a0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 limits using [sq
1d5b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
1d5c0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 * and limiting d
1d5d0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 atabase size usi
1d5e0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 ng the [max_page
1d5f0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
1d600 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .** in addition
1d610 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 to using an auth
1d620 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 orizer..**.** ^(
1d630 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 Only a single au
1d640 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 thorizer can be
1d650 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 in place on a da
1d660 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1d670 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 n.** at a time.
1d680 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
1d690 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1d6a0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 izer overrides t
1d6b0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 he.** previous c
1d6c0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 all.)^ ^Disable
1d6d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1d6e0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
1d6f0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
1d700 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
1d710 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
1d720 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 default..**.** T
1d730 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1d740 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
1d750 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
1d760 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
1d770 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1d780 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
1d790 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 oked the authori
1d7a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a zer callback..**
1d7b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
1d7c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1d7d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
1d7e0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
1d7f0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
1d800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
1d810 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
1d820 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
1d830 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
1d840 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c **.** ^When [sql
1d850 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1d860 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
1d870 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
1d880 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
1d890 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d ent might be re-
1d8a0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 prepared during
1d8b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1d8c0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 due to a .** sc
1d8d0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 hema change. He
1d8e0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 nce, the applica
1d8f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 tion should ensu
1d900 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 re that the.** c
1d910 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 orrect authorize
1d920 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 r callback remai
1d930 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 ns in place duri
1d940 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
1d950 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e step()]..**.** ^
1d960 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
1d970 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1d980 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
1d990 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c y during.** [sql
1d9a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
1d9b0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
1d9c0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 Authorization
1d9d0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 is not.** perfor
1d9e0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 med during state
1d9f0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 ment evaluation
1da00 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 in [sqlite3_step
1da10 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 ()], unless.** a
1da20 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 s stated in the
1da30 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 previous paragra
1da40 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ph, sqlite3_step
1da50 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 () invokes.** sq
1da60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1da70 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 () to reprepare
1da80 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 a statement afte
1da90 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 r a schema chang
1daa0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
1dab0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 int sqlite3_set
1dac0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 _authorizer(. s
1dad0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 qlite3*,. int (
1dae0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e *xAuth)(void*,in
1daf0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f t,const char*,co
1db00 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1db10 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1db20 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 *),. void *pUse
1db30 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 rData.);../*.**
1db40 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
1db50 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 izer Return Code
1db60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
1db70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1db80 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
1db90 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1dba0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 on] must.** retu
1dbb0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 rn either [SQLIT
1dbc0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 E_OK] or one of
1dbd0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 these two consta
1dbe0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 nts in order.**
1dbf0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 to signal SQLite
1dc00 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1dc10 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 the action is pe
1dc20 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 rmitted. See th
1dc30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 e.** [sqlite3_se
1dc40 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1dc50 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 uthorizer docume
1dc60 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 ntation] for add
1dc70 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
1dc80 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f mation..**.** No
1dc90 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 te that SQLITE_I
1dca0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 GNORE is also us
1dcb0 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f ed as a [SQLITE_
1dcc0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 ROLLBACK | retur
1dcd0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 n code].** from
1dce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 the [sqlite3_vta
1dcf0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d b_on_conflict()]
1dd00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 interface..*/.#
1dd10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1dd20 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 NY 1 /* Abor
1dd30 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
1dd40 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f ent with an erro
1dd50 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
1dd60 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f ITE_IGNORE 2 /
1dd70 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 * Don't allow ac
1dd80 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 cess, but don't
1dd90 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f generate an erro
1dda0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 r */../*.** CAPI
1ddb0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
1ddc0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a Action Codes.**
1ddd0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1dde0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1ddf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 )] interface reg
1de00 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
1de10 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 k function.** th
1de20 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f at is invoked to
1de30 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 authorize certa
1de40 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 in SQL statement
1de50 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a actions. The.*
1de60 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
1de70 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
1de80 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
1de90 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 code that speci
1dea0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 fies.** what act
1deb0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 ion is being aut
1dec0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 horized. These
1ded0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 are the integer
1dee0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 action codes tha
1def0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 t.** the authori
1df00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 zer callback may
1df10 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a be passed..**.*
1df20 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 * These action c
1df30 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 ode values signi
1df40 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 fy what kind of
1df50 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 operation is to
1df60 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 be.** authorized
1df70 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 . The 3rd and 4
1df80 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
1df90 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
1dfa0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 on.** callback f
1dfb0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 unction will be
1dfc0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
1dfd0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
1dfe0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a which of these.*
1dff0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 * codes is used
1e000 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
1e010 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 rameter. ^(The
1e020 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
1e030 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
1e040 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
1e050 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
1e060 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c atabase ("main",
1e070 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e "temp",.** etc.
1e080 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
1e090 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 )^ ^The 6th par
1e0a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
1e0b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1e0c0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 k.** is the name
1e0d0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f of the inner-mo
1e0e0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 st trigger or vi
1e0f0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f ew that is respo
1e100 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 nsible for.** th
1e110 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 e access attempt
1e120 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 or NULL if this
1e130 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
1e140 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d is directly from
1e150 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 .** top-level SQ
1e160 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a L code..*/./****
1e170 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1e180 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1e190 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a ******* 3rd ****
1e1a0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a ******** 4th ***
1e1b0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e ********/.#defin
1e1c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1e1d0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 INDEX 1
1e1e0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1e1f0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
1e200 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1e210 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1e220 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 ABLE 2
1e230 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1e240 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1e250 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1e260 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1e270 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 MP_INDEX 3
1e280 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1e290 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1e2a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1e2b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
1e2c0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 P_TABLE 4
1e2d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1e2e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1e2f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e300 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
1e310 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f _TRIGGER 5 /
1e320 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
1e330 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1e340 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e350 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
1e360 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a VIEW 6 /*
1e370 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
1e380 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1e390 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e3a0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 TE_CREATE_TRIGGE
1e3b0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 R 7 /*
1e3c0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
1e3d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1e3e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e3f0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 E_CREATE_VIEW
1e400 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 8 /* V
1e410 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
1e420 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1e430 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e440 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
1e450 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 9 /* Ta
1e460 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1e470 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1e480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e490 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 DROP_INDEX
1e4a0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 10 /* Ind
1e4b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1e4c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1e4d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1e4e0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ROP_TABLE
1e4f0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 11 /* Tabl
1e500 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1e510 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1e520 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1e530 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 OP_TEMP_INDEX
1e540 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 12 /* Index
1e550 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
1e560 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1e570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1e580 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 P_TEMP_TABLE
1e590 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 13 /* Table
1e5a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1e5b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1e5c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1e5d0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
1e5e0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 14 /* Trigger
1e5f0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1e600 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1e610 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1e620 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 TEMP_VIEW
1e630 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 15 /* View Nam
1e640 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1e650 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1e660 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1e670 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 RIGGER 1
1e680 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 6 /* Trigger N
1e690 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
1e6a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1e6b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 e SQLITE_DROP_VI
1e6c0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 EW 17
1e6d0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
1e6e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1e6f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1e700 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 SQLITE_INSERT
1e710 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 18
1e720 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1e730 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1e740 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1e750 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 SQLITE_PRAGMA
1e760 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 19
1e770 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 /* Pragma Name
1e780 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 1st arg or N
1e790 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ULL */.#define S
1e7a0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 QLITE_READ
1e7b0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 20
1e7c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1e7d0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
1e7e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e7f0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 LITE_SELECT
1e800 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 21 /
1e810 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
1e820 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1e830 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e840 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 ITE_TRANSACTION
1e850 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 22 /*
1e860 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
1e870 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1e880 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e890 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 TE_UPDATE
1e8a0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
1e8b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1e8c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
1e8d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e8e0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 E_ATTACH
1e8f0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 24 /* F
1e900 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e ilename N
1e910 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1e920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e930 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 _DETACH
1e940 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 25 /* Da
1e950 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 tabase Name NU
1e960 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1e970 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e980 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 ALTER_TABLE
1e990 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 26 /* Dat
1e9a0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 abase Name Tab
1e9b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1e9c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
1e9d0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 EINDEX
1e9e0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 27 /* Inde
1e9f0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c x Name NULL
1ea00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1ea10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
1ea20 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 ALYZE
1ea30 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 28 /* Table
1ea40 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1ea50 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1ea60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1ea70 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ATE_VTABLE
1ea80 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 29 /* Table
1ea90 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
1eaa0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1eab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1eac0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 _VTABLE
1ead0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 30 /* Table N
1eae0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
1eaf0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
1eb00 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 ine SQLITE_FUNCT
1eb10 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 ION
1eb20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 31 /* NULL
1eb30 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e Function
1eb40 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 Name */.#defi
1eb50 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f ne SQLITE_SAVEPO
1eb60 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 INT 3
1eb70 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
1eb80 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 Savepoint
1eb90 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
1eba0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
1ebb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
1ebc0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
1ebd0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
1ebe0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
1ebf0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
1ec00 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 unctions.**.** T
1ec10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
1ec20 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 gister callback
1ec30 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 functions that c
1ec40 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a an be used for.*
1ec50 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 * tracing and pr
1ec60 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 ofiling the exec
1ec70 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 ution of SQL sta
1ec80 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e tements..**.** ^
1ec90 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
1eca0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
1ecb0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 by sqlite3_trac
1ecc0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 e() is invoked a
1ecd0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d t.** various tim
1ece0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 es when an SQL s
1ecf0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e tatement is bein
1ed00 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 g run by [sqlite
1ed10 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 3_step()]..** ^T
1ed20 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 he sqlite3_trace
1ed30 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 () callback is i
1ed40 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 nvoked with a UT
1ed50 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 F-8 rendering of
1ed60 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 the.** SQL stat
1ed70 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 ement text as th
1ed80 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 e statement firs
1ed90 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 t begins executi
1eda0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f ng..** ^(Additio
1edb0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 nal sqlite3_trac
1edc0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 e() callbacks mi
1edd0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 ght occur.** as
1ede0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 each triggered s
1edf0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 ubprogram is ent
1ee00 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 ered. The callb
1ee10 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 acks for trigger
1ee20 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 s.** contain a U
1ee30 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 TF-8 SQL comment
1ee40 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 that identifies
1ee50 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a the trigger.)^.
1ee60 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
1ee70 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d E_TRACE_SIZE_LIM
1ee80 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 IT] compile-time
1ee90 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
1eea0 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 sed to limit.**
1eeb0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 the length of [b
1eec0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 ound parameter]
1eed0 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 expansion in the
1eee0 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 output of sqlit
1eef0 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a e3_trace()..**.*
1ef00 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 * ^The callback
1ef10 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
1ef20 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 red by sqlite3_p
1ef30 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f rofile() is invo
1ef40 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 ked.** as each S
1ef50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e QL statement fin
1ef60 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f ishes. ^The pro
1ef70 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f file callback co
1ef80 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 ntains.** the or
1ef90 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
1efa0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 text and an est
1efb0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c imate of wall-cl
1efc0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 ock time.** of h
1efd0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 ow long that sta
1efe0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 tement took to r
1eff0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c un. ^The profil
1f000 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 e callback.** ti
1f010 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f me is in units o
1f020 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 f nanoseconds, h
1f030 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 owever the curre
1f040 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
1f050 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 n.** is only cap
1f060 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 able of millisec
1f070 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 ond resolution s
1f080 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 o the six least
1f090 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 significant.** d
1f0a0 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d igits in the tim
1f0b0 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 e are meaningles
1f0c0 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 s. Future versi
1f0d0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ons of SQLite.**
1f0e0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 might provide g
1f0f0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f reater resolutio
1f100 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 n on the profile
1f110 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 r callback. The
1f120 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 .** sqlite3_prof
1f130 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ile() function i
1f140 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 s considered exp
1f150 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 erimental and is
1f160 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 .** subject to c
1f170 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 hange in future
1f180 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
1f190 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 te..*/.SQLITE_AP
1f1a0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
1f1b0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 trace(sqlite3*,
1f1c0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f void(*xTrace)(vo
1f1d0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 id*,const char*)
1f1e0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 , void*);.SQLITE
1f1f0 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 _API SQLITE_EXPE
1f200 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 RIMENTAL void *s
1f210 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 qlite3_profile(s
1f220 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
1f230 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 (*xProfile)(void
1f240 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 *,const char*,sq
1f250 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 lite3_uint64), v
1f260 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
1f270 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 PI3REF: Query Pr
1f280 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 ogress Callbacks
1f290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1f2a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
1f2b0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e dler(D,N,X,P) in
1f2c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
1f2d0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 he callback.** f
1f2e0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 unction X to be
1f2f0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
1f300 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
1f310 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
1f320 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 o.** [sqlite3_ex
1f330 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
1f340 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c step()] and [sql
1f350 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1f360 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 ] for.** databas
1f370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 e connection D.
1f380 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
1f390 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 for this.** inte
1f3a0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
1f3b0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
1f3c0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
1f3d0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ery..**.** ^The
1f3e0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 parameter P is p
1f3f0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
1f400 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
1f410 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 ter to the .** c
1f420 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1f430 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 X. ^The parame
1f440 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d ter N is the num
1f450 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 ber of .** [virt
1f460 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 ual machine inst
1f470 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 ructions] that a
1f480 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 re evaluated bet
1f490 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a ween successive.
1f4a0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f ** invocations o
1f4b0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 f the callback X
1f4c0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 ..**.** ^Only a
1f4d0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 single progress
1f4e0 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 handler may be d
1f4f0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 efined at one ti
1f500 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 me per.** [datab
1f510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b ase connection];
1f520 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 setting a new p
1f530 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
1f540 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f cancels the.** o
1f550 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e ld one. ^Settin
1f560 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f g parameter X to
1f570 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 NULL disables t
1f580 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
1f590 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f ler..** ^The pro
1f5a0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 gress handler is
1f5b0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 also disabled b
1f5c0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 y setting N to a
1f5d0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 value less.** t
1f5e0 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 han 1..**.** ^If
1f5f0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 the progress ca
1f600 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
1f610 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 on-zero, the ope
1f620 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 ration is.** int
1f630 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 errupted. This
1f640 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 feature can be u
1f650 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
1f660 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 a.** "Cancel" b
1f670 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 utton on a GUI p
1f680 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 rogress dialog b
1f690 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ox..**.** The pr
1f6a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 ogress handler c
1f6b0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 allback must not
1f6c0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
1f6d0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
1f6e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1f6f0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
1f700 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 voked the progre
1f710 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e ss handler..** N
1f720 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
1f730 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1f740 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
1f750 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
1f760 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
1f770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
1f780 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
1f790 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
1f7a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
1f7b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
1f7c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 oid sqlite3_prog
1f7d0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c ress_handler(sql
1f7e0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 ite3*, int, int(
1f7f0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a *)(void*), void*
1f800 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1f810 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 EF: Opening A Ne
1f820 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 w Database Conne
1f830 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ction.**.** ^The
1f840 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e se routines open
1f850 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 an SQLite datab
1f860 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 ase file as spec
1f870 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a ified by the .**
1f880 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
1f890 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d nt. ^The filenam
1f8a0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e e argument is in
1f8b0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 terpreted as UTF
1f8c0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 -8 for.** sqlite
1f8d0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
1f8e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 ite3_open_v2() a
1f8f0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 nd as UTF-16 in
1f900 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a the native byte.
1f910 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c ** order for sql
1f920 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e ite3_open16(). ^
1f930 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e (A [database con
1f940 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
1f950 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 is usually.** re
1f960 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c turned in *ppDb,
1f970 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f even if an erro
1f980 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f r occurs. The o
1f990 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 nly exception is
1f9a0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 that.** if SQLi
1f9b0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
1f9c0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
1f9d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c to hold the [sql
1f9e0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a ite3] object,.**
1f9f0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 a NULL will be
1fa00 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 written into *pp
1fa10 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 Db instead of a
1fa20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
1fa30 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 sqlite3].** obje
1fa40 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 ct.)^ ^(If the d
1fa50 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
1fa60 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 d (and/or create
1fa70 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c d) successfully,
1fa80 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 then.** [SQLITE
1fa90 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
1faa0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 . Otherwise an
1fab0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
1fac0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 returned.)^ ^The
1fad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
1fae0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 msg()] or [sqlit
1faf0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 e3_errmsg16()] r
1fb00 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
1fb10 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
1fb20 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
1fb30 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
1fb40 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f of the error fo
1fb50 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 llowing a failur
1fb60 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 e of any.** of t
1fb70 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 he sqlite3_open(
1fb80 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a ) routines..**.*
1fb90 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 * ^The default e
1fba0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 ncoding for the
1fbb0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
1fbc0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c UTF-8 if.** sql
1fbd0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
1fbe0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1fbf0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a is called and.*
1fc00 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 * UTF-16 in the
1fc10 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
1fc20 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 r if sqlite3_ope
1fc30 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a n16() is used..*
1fc40 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 *.** Whether or
1fc50 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 not an error occ
1fc60 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f urs when it is o
1fc70 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 pened, resources
1fc80 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
1fc90 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
1fca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
1fcb0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 ndle should be r
1fcc0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 eleased by.** pa
1fcd0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
1fce0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 ite3_close()] wh
1fcf0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 en it is no long
1fd00 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a er required..**.
1fd10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
1fd20 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 pen_v2() interfa
1fd30 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 ce works like sq
1fd40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 lite3_open().**
1fd50 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
1fd60 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 ccepts two addit
1fd70 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 ional parameters
1fd80 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
1fd90 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 control.** over
1fda0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
1fdb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 connection. ^(
1fdc0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
1fdd0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ter to.** sqlite
1fde0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 3_open_v2() can
1fdf0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 take one of.** t
1fe00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
1fe10 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f ee values, optio
1fe20 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
1fe30 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ith the .** [SQL
1fe40 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
1fe50 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
1fe60 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c FULLMUTEX], [SQL
1fe70 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
1fe80 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ACHE],.** [SQLIT
1fe90 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
1fea0 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 CHE], and/or [SQ
1feb0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
1fec0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 lags:)^.**.** <d
1fed0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c l>.** ^(<dt>[SQL
1fee0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
1fef0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 Y]</dt>.** <dd>T
1ff00 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
1ff10 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e pened in read-on
1ff20 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ly mode. If the
1ff30 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e database does n
1ff40 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 ot.** already ex
1ff50 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 ist, an error is
1ff60 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
1ff70 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
1ff80 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
1ff90 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RITE]</dt>.** <d
1ffa0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
1ffb0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
1ffc0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
1ffd0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 if possible, or
1ffe0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 reading.** only
1fff0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 if the file is
20000 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 write protected
20010 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 by the operating
20020 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 system. In eit
20030 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 her.** case the
20040 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c database must al
20050 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 ready exist, oth
20060 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 erwise an error
20070 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
20080 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
20090 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
200a0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
200b0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f E_OPEN_CREATE]</
200c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
200d0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
200e0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
200f0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 d writing, and i
20100 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 s created if.**
20110 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 it does not alre
20120 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 ady exist. This
20130 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 is the behavior
20140 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
20150 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 sed for.** sqlit
20160 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
20170 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c lite3_open16().<
20180 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
20190 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 **.** If the 3rd
201a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
201b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
201c0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 is not one of th
201d0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e e.** combination
201e0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 s shown above op
201f0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
20200 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 d with other.**
20210 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
20220 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f DONLY | SQLITE_O
20230 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 PEN_* bits].** t
20240 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
20250 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
20260 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 *.** ^If the [SQ
20270 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
20280 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
20290 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
202a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
202b0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
202c0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
202d0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
202e0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
202f0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
20300 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
20310 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
20320 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
20330 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
20340 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
20350 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 EX] flag is set
20360 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
20370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
20380 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 ns.** in the ser
20390 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
203a0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 ng mode] unless
203b0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 single-thread wa
203c0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 s.** previously
203d0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 selected at comp
203e0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 ile-time or star
203f0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 t-time..** ^The
20400 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
20410 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 REDCACHE] flag c
20420 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
20430 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
20440 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 be.** eligible
20450 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 to use [shared c
20460 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 ache mode], rega
20470 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
20480 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a r or not shared.
20490 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 ** cache is enab
204a0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 led using [sqlit
204b0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
204c0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 _cache()]. ^The
204d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
204e0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 _PRIVATECACHE] f
204f0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
20500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20510 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 on to not.** par
20520 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 ticipate in [sha
20530 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 red cache mode]
20540 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e even if it is en
20550 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
20560 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
20570 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
20580 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
20590 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
205a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
205b0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
205c0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
205d0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
205e0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
205f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20600 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
20610 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 ^If the fourth p
20620 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 arameter is.** a
20630 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
20640 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b en the default [
20650 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
20660 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ect is used..**.
20670 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e ** ^If the filen
20680 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a ame is ":memory:
20690 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 ", then a privat
206a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d e, temporary in-
206b0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a memory database.
206c0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f ** is created fo
206d0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
206e0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f . ^This in-memo
206f0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c ry database will
20700 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 vanish when.**
20710 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
20720 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
20730 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 d. Future versi
20740 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
20750 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 ght.** make use
20760 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 of additional sp
20770 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 ecial filenames
20780 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 that begin with
20790 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 the ":" characte
207a0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f r..** It is reco
207b0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 mmended that whe
207c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c n a database fil
207d0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 ename actually d
207e0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a oes begin with.*
207f0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 * a ":" characte
20800 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 r you should pre
20810 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 fix the filename
20820 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 with a pathname
20830 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 such as.** "./"
20840 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 to avoid ambigu
20850 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ity..**.** ^If t
20860 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 he filename is a
20870 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
20880 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
20890 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d temporary.** on-
208a0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 disk database wi
208b0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 ll be created.
208c0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 ^This private da
208d0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a tabase will be.*
208e0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
208f0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 deleted as soon
20900 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 as the database
20910 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
20920 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 osed..**.** [[UR
20930 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 I filenames in s
20940 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 qlite3_open()]]
20950 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 <h3>URI Filename
20960 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 s</h3>.**.** ^If
20970 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 [URI filename]
20980 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
20990 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 s enabled, and t
209a0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
209b0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 ment.** begins w
209c0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 ith "file:", the
209d0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 n the filename i
209e0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
209f0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 a URI. ^URI.**
20a00 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 filename interpr
20a10 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c etation is enabl
20a20 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 ed if the [SQLIT
20a30 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
20a40 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 is.** set in th
20a50 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
20a60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 t to sqlite3_ope
20a70 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 n_v2(), or if it
20a80 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 has.** been ena
20a90 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 bled globally us
20aa0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
20ab0 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 CONFIG_URI] opti
20ac0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b on with the.** [
20ad0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
20ae0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 ] method or by t
20af0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 he [SQLITE_USE_U
20b00 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 RI] compile-time
20b10 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f option..** As o
20b20 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
20b30 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 3.7.7, URI file
20b40 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 name interpretat
20b50 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 ion is turned of
20b60 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c f.** by default,
20b70 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 but future rele
20b80 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ases of SQLite m
20b90 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 ight enable URI
20ba0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 filename.** inte
20bb0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 rpretation by de
20bc0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 fault. See "[UR
20bd0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f I filenames]" fo
20be0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
20bf0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
20c00 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 ** URI filenames
20c10 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f are parsed acco
20c20 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 rding to RFC 398
20c30 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6. ^If the URI c
20c40 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 ontains an.** au
20c50 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 thority, then it
20c60 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
20c70 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
20c80 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a or the string .*
20c90 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e * "localhost". ^
20ca0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 If the authority
20cb0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 is not an empty
20cc0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 string or "loca
20cd0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 lhost", an .** e
20ce0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
20cf0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 to the caller.
20d00 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f ^The fragment co
20d10 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
20d20 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 , if .** present
20d30 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a , is ignored..**
20d40 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
20d50 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e the path compon
20d60 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 ent of the URI a
20d70 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
20d80 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 e disk file.** w
20d90 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 hich contains th
20da0 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 e database. ^If
20db0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 the path begins
20dc0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 with a '/' chara
20dd0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 cter, .** then i
20de0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
20df0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 as an absolute
20e00 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 path. ^If the pa
20e10 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 th does not begi
20e20 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 n .** with a '/'
20e30 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 (meaning that t
20e40 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 he authority sec
20e50 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 tion is omitted
20e60 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a from the URI).**
20e70 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 then the path i
20e80 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
20e90 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 a relative path
20ea0 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 . .** ^On window
20eb0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d s, the first com
20ec0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 ponent of an abs
20ed0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 olute path .** i
20ee0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 s a drive specif
20ef0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 ication (e.g. "C
20f00 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 :")..**.** [[cor
20f10 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 e URI query para
20f20 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 meters]].** The
20f30 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 query component
20f40 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e of a URI may con
20f50 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 tain parameters
20f60 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 that are interpr
20f70 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 eted.** either b
20f80 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c y SQLite itself,
20f90 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 or by a [VFS |
20fa0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 custom VFS imple
20fb0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 mentation]..** S
20fc0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 QLite interprets
20fd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
20fe0 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d hree query param
20ff0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c eters:.**.** <ul
21000 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 >.** <li> <b>v
21010 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 fs</b>: ^The "vf
21020 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 s" parameter may
21030 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 be used to spec
21040 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a ify the name of.
21050 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a ** a VFS obj
21060 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 ect that provide
21070 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 s the operating
21080 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 system interface
21090 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 that should.**
210a0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 be used to a
210b0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
210c0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e se file on disk.
210d0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e ^If this option
210e0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 is set to.**
210f0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e an empty strin
21100 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 g the default VF
21110 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 S object is used
21120 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e . ^Specifying an
21130 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 unknown.**
21140 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e VFS is an error.
21150 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 ^If sqlite3_ope
21160 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 n_v2() is used a
21170 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f nd the vfs optio
21180 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 n is.** pres
21190 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 ent, then the VF
211a0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 S specified by t
211b0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 he option takes
211c0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a precedence over.
211d0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 ** the value
211e0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
211f0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
21200 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
21210 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c v2()..**.** <l
21220 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 i> <b>mode</b>:
21230 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d ^(The mode param
21240 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 eter may be set
21250 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 to either "ro",
21260 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 "rw",.** "rw
21270 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e c", or "memory".
21280 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 Attempting to s
21290 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 et it to any oth
212a0 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 er value is.**
212b0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a an error)^. .
212c0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 ** ^If "ro"
212d0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 is specified, th
212e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
212f0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
21300 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 ad-only .**
21310 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 access, just as
21320 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
21330 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c PEN_READONLY] fl
21340 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 ag had been set
21350 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 in the .** t
21360 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
21370 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
21380 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 (). ^If the mode
21390 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 option is set t
213a0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 o .** "rw",
213b0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
213c0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
213d0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 read-write (but
213e0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 not create) .**
213f0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 access, as i
21400 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 f SQLITE_OPEN_RE
21410 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 ADWRITE (but not
21420 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
21430 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 ATE) had .**
21440 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 been set. ^Valu
21450 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 e "rwc" is equiv
21460 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
21470 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 both .** SQ
21480 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
21490 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f ITE and SQLITE_O
214a0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 PEN_CREATE. ^If
214b0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e the mode option
214c0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 is.** set t
214d0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 o "memory" then
214e0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 a pure [in-memor
214f0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 y database] that
21500 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 never reads.**
21510 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 or writes fr
21520 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e om disk is used.
21530 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 ^It is an error
21540 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 to specify a va
21550 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 lue for.** t
21560 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 he mode paramete
21570 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 r that is less r
21580 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 estrictive than
21590 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 that specified b
215a0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 y.** the fla
215b0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 gs passed in the
215c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
215d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
215e0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c _v2()..**.** <
215f0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e li> <b>cache</b>
21600 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 : ^The cache par
21610 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 ameter may be se
21620 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 t to either "sha
21630 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 red" or.** "
21640 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 private". ^Setti
21650 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 ng it to "shared
21660 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
21670 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a to setting the.*
21680 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
21690 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 N_SHAREDCACHE bi
216a0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 t in the flags a
216b0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 rgument passed t
216c0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 o.** sqlite3
216d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 _open_v2(). ^Set
216e0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 ting the cache p
216f0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 arameter to "pri
21700 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 vate" is .**
21710 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
21720 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 etting the SQLIT
21730 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
21740 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 CHE bit..**
21750 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
21760 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e _v2() is used an
21770 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 d the "cache" pa
21780 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 rameter is prese
21790 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 nt in.** a U
217a0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 RI filename, its
217b0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 value overrides
217c0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 any behavior re
217d0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 quested by setti
217e0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 ng.** SQLITE
217f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
21800 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 HE or SQLITE_OPE
21810 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c N_SHAREDCACHE fl
21820 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a ag..** </ul>.**.
21830 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 ** ^Specifying a
21840 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 n unknown parame
21850 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 ter in the query
21860 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
21870 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a URI is not an.**
21880 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 error. Future
21890 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
218a0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 te might underst
218b0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 and additional q
218c0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
218d0 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 rs. See "[query
218e0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 parameters with
218f0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 special meaning
21900 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 to SQLite]" for
21910 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 .** additional i
21920 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
21930 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 * [[URI filename
21940 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e examples]] <h3>
21950 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 URI filename exa
21960 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a mples</h3>.**.**
21970 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
21980 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 1" align=center
21990 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a cellpadding=5>.*
219a0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 * <tr><th> URI f
219b0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 ilenames <th> Re
219c0 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 sults.** <tr><td
219d0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c > file:data.db <
219e0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
219f0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 Open the file "
21a00 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 data.db" in the
21a10 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 current director
21a20 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 y..** <tr><td> f
21a30 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 ile:/home/fred/d
21a40 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 ata.db<br>.**
21a50 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 file:///h
21a60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
21a70 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <br> .**
21a80 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 file://localh
21a90 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 ost/home/fred/da
21aa0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 ta.db <br> <td>
21ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
21ac0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
21ad0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
21ae0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 data.db"..** <tr
21af0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 ><td> file://dar
21b00 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f kstar/home/fred/
21b10 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a data.db <td> .**
21b20 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
21b30 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 or. "darkstar" i
21b40 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a s not a recogniz
21b50 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a ed authority..**
21b60 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 <tr><td style="
21b70 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 white-space:nowr
21b80 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 ap"> .**
21b90 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 file:///C:/Doc
21ba0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 uments%20and%20S
21bb0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 ettings/fred/Des
21bc0 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 ktop/data.db.**
21bd0 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 <td> Windows
21be0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 only: Open the
21bf0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f file "data.db" o
21c00 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 n fred's desktop
21c10 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 on drive.**
21c20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 C:. Note t
21c30 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 hat the %20 esca
21c40 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 ping in this exa
21c50 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 mple is not stri
21c60 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 ctly .**
21c70 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 necessary - sp
21c80 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 ace characters c
21c90 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 an be used liter
21ca0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 ally.**
21cb0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 in URI filename
21cc0 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 s..** <tr><td> f
21cd0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 ile:data.db?mode
21ce0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 =ro&cache=privat
21cf0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 e <td> .**
21d00 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 Open file "d
21d10 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
21d20 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
21d30 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 for read-only a
21d40 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 ccess..**
21d50 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 Regardless of
21d60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
21d70 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 shared-cache mod
21d80 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a e is enabled by.
21d90 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 ** defa
21da0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 ult, use a priva
21db0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 te cache..** <tr
21dc0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 ><td> file:/home
21dd0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 /fred/data.db?vf
21de0 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 s=unix-nolock <t
21df0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f d>.** O
21e00 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f pen file "/home/
21e10 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 fred/data.db". U
21e20 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 se the special V
21e30 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 FS "unix-nolock"
21e40 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
21e50 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
21e60 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a readonly <td> .*
21e70 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 * An er
21e80 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 ror. "readonly"
21e90 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f is not a valid o
21ea0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d ption for the "m
21eb0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a ode" parameter..
21ec0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a ** </table>.**.*
21ed0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d * ^URI hexadecim
21ee0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
21ef0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 ces (%HH) are su
21f00 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 pported within t
21f10 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 he path and.** q
21f20 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 uery components
21f30 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 of a URI. A hexa
21f40 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
21f50 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 equence consists
21f60 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 of a.** percent
21f70 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f sign - "%" - fo
21f80 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c llowed by exactl
21f90 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 y two hexadecima
21fa0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 l digits .** spe
21fb0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 cifying an octet
21fc0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 value. ^Before
21fd0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 the path or quer
21fe0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 y components of
21ff0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d a.** URI filenam
22000 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 e are interprete
22010 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f d, they are enco
22020 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 ded using UTF-8
22030 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 and all .** hexa
22040 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
22050 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 equences replace
22060 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 d by a single by
22070 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 te containing th
22080 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 e.** correspondi
22090 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 ng octet. If thi
220a0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 s process genera
220b0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 tes an invalid U
220c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a TF-8 encoding,.*
220d0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 * the results ar
220e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
220f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 ** <b>Note to Wi
22100 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e ndows users:</b>
22110 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 The encoding u
22120 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 sed for the file
22130 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a name argument.**
22140 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e of sqlite3_open
22150 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
22160 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 pen_v2() must be
22170 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 UTF-8, not what
22180 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 ever.** codepage
22190 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 is currently de
221a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 fined. Filename
221b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 s containing int
221c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 ernational.** ch
221d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 aracters must be
221e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 converted to UT
221f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 F-8 prior to pas
22200 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a sing them into.*
22210 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
22220 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
22230 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e _v2()..**.** <b>
22240 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 Note to Windows
22250 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f Runtime users:</
22260 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 b> The temporar
22270 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 y directory must
22280 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 be set.** prior
22290 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 to calling sqli
222a0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
222b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
222c0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 Otherwise, var
222d0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 ious.** features
222e0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 that require th
222f0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 e use of tempora
22300 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 ry files may fai
22310 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 l..**.** See als
22320 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 o: [sqlite3_temp
22330 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 _directory].*/.S
22340 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
22350 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
22360 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
22370 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
22380 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
22390 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
223a0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
223b0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
223c0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 b handle */.);.S
223d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
223e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 lite3_open16(.
223f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 const void *file
22400 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
22410 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
22420 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 F-16) */. sqlit
22430 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
22440 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
22450 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
22460 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
22470 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
22480 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
22490 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
224a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
224b0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
224c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 lite3 **ppDb,
224d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
224e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
224f0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 /. int flags,
22500 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 /* F
22510 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 lags */. const
22520 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 char *zVfs
22530 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 /* Name of VFS
22540 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a module to use *
22550 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
22560 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 3REF: Obtain Val
22570 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 ues For URI Para
22580 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 meters.**.** The
22590 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 se are utility r
225a0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 outines, useful
225b0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 to VFS implement
225c0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 ations, that che
225d0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 ck.** to see if
225e0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
225f0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 was a URI that c
22600 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 ontained a speci
22610 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 fic query .** pa
22620 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 rameter, and if
22630 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 so obtains the v
22640 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 alue of that que
22650 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ry parameter..**
22660 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 .** If F is the
22670 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d database filenam
22680 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 e pointer passed
22690 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 into the xOpen(
226a0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 ) method of .**
226b0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 a VFS implementa
226c0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c tion when the fl
226d0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
226e0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 xOpen() has one
226f0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 or .** more of
22700 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
22710 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 _URI] or [SQLITE
22720 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 _OPEN_MAIN_DB] b
22730 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 its set and.** P
22740 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
22750 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 the query parame
22760 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c ter, then.** sql
22770 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
22780 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 er(F,P) returns
22790 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
227a0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 P.** parameter
227b0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 if it exists or
227c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
227d0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 f P does not app
227e0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 ear as a .** que
227f0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 ry parameter on
22800 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 F. If P is a qu
22810 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 ery parameter of
22820 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 F.** has no exp
22830 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 licit value, the
22840 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 n sqlite3_uri_pa
22850 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
22860 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 urns.** a pointe
22870 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 r to an empty st
22880 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ring..**.** The
22890 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
228a0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 ean(F,P,B) routi
228b0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ne assumes that
228c0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a P is a boolean.*
228d0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 * parameter and
228e0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 returns true (1)
228f0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 or false (0) ac
22900 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 cording to the v
22910 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 alue.** of P. T
22920 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 he sqlite3_uri_b
22930 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f oolean(F,P,B) ro
22940 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 utine returns tr
22950 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a ue (1) if the.**
22960 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 value of query
22970 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f parameter P is o
22980 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 ne of "yes", "tr
22990 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 ue", or "on" in
229a0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 any.** case or i
229b0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 f the value begi
229c0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 ns with a non-ze
229d0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 ro number. The
229e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f .** sqlite3_uri_
229f0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
22a00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 outines returns
22a10 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 false (0) if the
22a20 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 value of.** que
22a30 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 ry parameter P i
22a40 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 s one of "no", "
22a50 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 false", or "off"
22a60 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a in any case or.
22a70 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 ** if the value
22a80 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 begins with a nu
22a90 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 meric zero. If
22aa0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 P is not a query
22ab0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e .** parameter on
22ac0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c F or if the val
22ad0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 ue of P is does
22ae0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 not match any of
22af0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 the.** above, t
22b00 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f hen sqlite3_uri_
22b10 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
22b20 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a eturns (B!=0)..*
22b30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
22b40 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 _uri_int64(F,P,D
22b50 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 ) routine conver
22b60 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ts the value of
22b70 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 P into a.** 64-b
22b80 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
22b90 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 r and returns th
22ba0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 at integer, or D
22bb0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a if P does not.*
22bc0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 * exist. If the
22bd0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 value of P is s
22be0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
22bf0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 han an integer,
22c00 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 then.** zero is
22c10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a returned..** .**
22c20 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 If F is a NULL
22c30 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 pointer, then sq
22c40 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
22c50 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 ter(F,P) returns
22c60 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c NULL and.** sql
22c70 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
22c80 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 (F,P,B) returns
22c90 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 B. If F is not
22ca0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 a NULL pointer a
22cb0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 nd.** is not a d
22cc0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 atabase file pat
22cd0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 hname pointer th
22ce0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 at SQLite passed
22cf0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a into the xOpen.
22d00 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 ** VFS method, t
22d10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
22d20 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
22d30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
22d40 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e d probably.** un
22d50 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 desirable..*/.SQ
22d60 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
22d70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 har *sqlite3_uri
22d80 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 _parameter(const
22d90 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
22da0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
22db0 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 aram);.SQLITE_AP
22dc0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 I int sqlite3_ur
22dd0 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 i_boolean(const
22de0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e char *zFile, con
22df0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c st char *zParam,
22e00 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a int bDefault);.
22e10 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
22e20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
22e30 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 _uri_int64(const
22e40 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 char*, const ch
22e50 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 ar*, sqlite3_int
22e60 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 64);.../*.** CAP
22e70 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 I3REF: Error Cod
22e80 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a es And Messages.
22e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
22ea0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 e3_errcode() int
22eb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
22ec0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 he numeric [resu
22ed0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b lt code] or.** [
22ee0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
22ef0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f code] for the mo
22f00 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 st recent failed
22f10 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 sqlite3_* API c
22f20 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 all.** associate
22f30 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
22f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
22f50 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 If a prior API c
22f60 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 all failed.** bu
22f70 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e t the most recen
22f80 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 t API call succe
22f90 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e eded, the return
22fa0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 value from.** s
22fb0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
22fc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
22fd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
22fe0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a ended_errcode().
22ff0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
23000 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 the same except
23010 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 that it always r
23020 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b eturns the .** [
23030 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
23040 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 code] even when
23050 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
23060 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 codes are.** dis
23070 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
23080 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 e sqlite3_errmsg
23090 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 () and sqlite3_e
230a0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e rrmsg16() return
230b0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
230c0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 e.** text that d
230d0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
230e0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 or, as either UT
230f0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 F-8 or UTF-16 re
23100 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
23110 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 (Memory to hold
23120 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
23130 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
23140 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a ged internally..
23150 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
23160 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
23170 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 to worry about
23180 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 freeing the resu
23190 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 lt..** However,
231a0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 the error string
231b0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 might be overwr
231c0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 itten or dealloc
231d0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 ated by.** subse
231e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f quent calls to o
231f0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
23200 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e rface functions.
23210 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
23220 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 lite3_errstr() i
23230 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
23240 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e the English-lan
23250 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 guage text.** th
23260 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
23270 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 [result code],
23280 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d as UTF-8..** ^(M
23290 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
232a0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
232b0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 string is manage
232c0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 d internally.**
232d0 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 and must not be
232e0 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 freed by the app
232f0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a lication)^..**.*
23300 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 * When the seria
23310 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
23320 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 mode] is in use
23330 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 , it might be th
23340 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 e.** case that a
23350 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 second error oc
23360 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 curs on a separa
23370 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 te thread in bet
23380 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 ween.** the time
23390 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 of the first er
233a0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c ror and the call
233b0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
233c0 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 aces..** When th
233d0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 at happens, the
233e0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c second error wil
233f0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 l be reported si
23400 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 nce these.** int
23410 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 erfaces always r
23420 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 eport the most r
23430 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 ecent result. T
23440 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c o avoid.** this,
23450 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e each thread can
23460 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 obtain exclusiv
23470 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 e use of the [da
23480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
23490 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b n] D.** by invok
234a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
234b0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 ex_enter]([sqlit
234c0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
234d0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e before beginnin
234e0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e g.** to use D an
234f0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 d invoking [sqli
23500 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d te3_mutex_leave]
23510 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
23520 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a ex](D)) after.**
23530 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 all calls to th
23540 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 e interfaces lis
23550 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d ted here are com
23560 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 pleted..**.** If
23570 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 an interface fa
23580 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f ils with SQLITE_
23590 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 MISUSE, that mea
235a0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ns the interface
235b0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 .** was invoked
235c0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 incorrectly by t
235d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
235e0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 In that case, t
235f0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 he.** error code
23600 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 and message may
23610 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 or may not be s
23620 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 et..*/.SQLITE_AP
23630 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 I int sqlite3_er
23640 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 rcode(sqlite3 *d
23650 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 b);.SQLITE_API i
23660 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
23670 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 ded_errcode(sqli
23680 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 te3 *db);.SQLITE
23690 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
236a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 *sqlite3_errmsg(
236b0 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 sqlite3*);.SQLIT
236c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
236d0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
236e0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 16(sqlite3*);.SQ
236f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
23700 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 har *sqlite3_err
23710 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a str(int);../*.**
23720 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 CAPI3REF: SQL S
23730 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
23740 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
23750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23760 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
23770 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
23780 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
23790 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
237a0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
237b0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 statement..** T
237c0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 his object is va
237d0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 riously known as
237e0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 a "prepared sta
237f0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 tement" or a.**
23800 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 "compiled SQL st
23810 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 atement" or simp
23820 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 ly as a "stateme
23830 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c nt"..**.** The l
23840 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 ife of a stateme
23850 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 nt object goes s
23860 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 omething like th
23870 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a is:.**.** <ol>.*
23880 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 * <li> Create th
23890 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
238a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
238b0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 v2()] or a relat
238c0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 ed.** funct
238d0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e ion..** <li> Bin
238e0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 d values to [hos
238f0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 t parameters] us
23900 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
23910 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 bind_*().**
23920 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
23930 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c <li> Run the SQL
23940 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
23950 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 ite3_step()] one
23960 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
23970 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 ** <li> Reset th
23980 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e e statement usin
23990 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
239a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b ()] then go back
239b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 .** to step
239c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 2. Do this zer
239d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e o or more times.
239e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 .** <li> Destroy
239f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
23a00 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
23a10 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e ize()]..** </ol>
23a20 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 .**.** Refer to
23a30 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e documentation on
23a40 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 individual meth
23a50 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 ods above for ad
23a60 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
23a70 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 rmation..*/.type
23a80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
23a90 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f e3_stmt sqlite3_
23aa0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 stmt;../*.** CAP
23ab0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 I3REF: Run-time
23ac0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 Limits.**.** ^(T
23ad0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
23ae0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 lows the size of
23af0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 various constru
23b00 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 cts to be limite
23b10 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 d.** on a connec
23b20 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 tion by connecti
23b30 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 on basis. The f
23b40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
23b50 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 s the.** [databa
23b60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 se connection] w
23b70 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f hose limit is to
23b80 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 be set or queri
23b90 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f ed. The.** seco
23ba0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
23bb0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 one of the [limi
23bc0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 t categories] th
23bd0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 at define a.** c
23be0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 lass of construc
23bf0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 ts to be size li
23c00 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 mited. The thir
23c10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
23c20 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 he.** new limit
23c30 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 for that constru
23c40 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ct.)^.**.** ^If
23c50 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 the new limit is
23c60 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 a negative numb
23c70 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 er, the limit is
23c80 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e unchanged..** ^
23c90 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 (For each limit
23ca0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f category SQLITE_
23cb0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 LIMIT_<i>NAME</i
23cc0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a > there is a .**
23cd0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 [limits | hard
23ce0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 upper bound].**
23cf0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 set at compile-t
23d00 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 ime by a C prepr
23d10 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 ocessor macro ca
23d20 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 lled.** [limits
23d30 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e | SQLITE_MAX_<i>
23d40 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 NAME</i>]..** (T
23d50 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 he "_LIMIT_" in
23d60 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e the name is chan
23d70 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 ged to "_MAX_".)
23d80 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 )^.** ^Attempts
23d90 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 to increase a li
23da0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 mit above its ha
23db0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 rd upper bound a
23dc0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 re.** silently t
23dd0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 runcated to the
23de0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
23df0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c ..**.** ^Regardl
23e00 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
23e10 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 r not the limit
23e20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 was changed, the
23e30 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 .** [sqlite3_li
23e40 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 mit()] interface
23e50 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 returns the pri
23e60 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 or value of the
23e70 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 limit..** ^Hence
23e80 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 , to find the cu
23e90 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 rrent value of a
23ea0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 limit without c
23eb0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 hanging it,.** s
23ec0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 imply invoke thi
23ed0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 s interface with
23ee0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
23ef0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a eter set to -1..
23f00 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c **.** Run-time l
23f10 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 imits are intend
23f20 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 ed for use in ap
23f30 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
23f40 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 manage.** both t
23f50 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 heir own interna
23f60 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 l database and a
23f70 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 lso databases th
23f80 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 at are controlle
23f90 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 d.** by untruste
23fa0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 d external sourc
23fb0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 es. An example
23fc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 application migh
23fd0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 t be a.** web br
23fe0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 owser that has i
23ff0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 ts own databases
24000 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 for storing his
24010 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 tory and.** sepa
24020 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 rate databases c
24030 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 ontrolled by Jav
24040 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 aScript applicat
24050 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a ions downloaded.
24060 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 ** off the Inter
24070 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e net. The intern
24080 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e al databases can
24090 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a be given the.**
240a0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 large, default
240b0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 limits. Databas
240c0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 es managed by ex
240d0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 ternal sources c
240e0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d an.** be given m
240f0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 uch smaller limi
24100 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 ts designed to p
24110 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 revent a denial
24120 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 of service.** at
24130 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 tack. Developer
24140 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e s might also wan
24150 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 t to use the [sq
24160 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
24170 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 izer()].** inter
24180 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 face to further
24190 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 control untruste
241a0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 d SQL. The size
241b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
241c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 .** created by a
241d0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 n untrusted scri
241e0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 pt can be contai
241f0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ned using the.**
24200 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
24210 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a ] [PRAGMA]..**.*
24220 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c * New run-time l
24230 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 imit categories
24240 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
24250 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
24260 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
24270 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 nt sqlite3_limit
24280 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 (sqlite3*, int i
24290 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a d, int newVal);.
242a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
242b0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 Run-Time Limit
242c0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 Categories.** KE
242d0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
242e0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 ategory} {*limit
242f0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a categories}.**.
24300 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
24310 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
24320 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 s performance li
24330 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e mits.** that can
24340 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 be lowered at r
24350 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 un-time using [s
24360 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
24370 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 .** The synopsis
24380 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 of the meanings
24390 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
243a0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 limits is shown
243b0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 below..** Additi
243c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
243d0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 is available at
243e0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 [limits | Limit
243f0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a s in SQLite]..**
24400 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
24410 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
24420 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
24430 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 _LIMIT_LENGTH</d
24440 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
24450 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e ximum size of an
24460 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 y string or BLOB
24470 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 or table row, i
24480 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a n bytes.<dd>)^.*
24490 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
244a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d MIT_SQL_LENGTH]]
244b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
244c0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
244d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
244e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
244f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
24500 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 t, in bytes.</dd
24510 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
24520 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d TE_LIMIT_COLUMN]
24530 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
24540 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e IMIT_COLUMN</dt>
24550 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
24560 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
24570 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 lumns in a table
24580 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 definition or i
24590 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 n the.** result
245a0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
245b0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d ] or the maximum
245c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
245d0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a ns in an index.*
245e0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 * or in an ORDER
245f0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 BY or GROUP BY
24600 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a clause.</dd>)^.*
24610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
24620 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d MIT_EXPR_DEPTH]]
24630 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
24640 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f MIT_EXPR_DEPTH</
24650 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
24660 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
24670 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f the parse tree o
24680 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e n any expression
24690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
246a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f [SQLITE_LIMIT_CO
246b0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 MPOUND_SELECT]]
246c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
246d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
246e0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CT</dt>.** <dd>T
246f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
24700 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 r of terms in a
24710 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 compound SELECT
24720 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 statement.</dd>)
24730 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
24740 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d _LIMIT_VDBE_OP]]
24750 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
24760 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
24770 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
24780 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
24790 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
247a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
247b0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
247c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
247d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
247e0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f This limit is no
247f0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 t currently.** e
24800 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 nforced, though
24810 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 that might be ad
24820 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ded in some futu
24830 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a re release of.**
24840 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a SQLite.</dd>)^.
24850 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
24860 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
24870 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 G]] ^(<dt>SQLITE
24880 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
24890 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
248a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
248b0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
248c0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
248d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
248e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
248f0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 HED]] ^(<dt>SQLI
24900 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
24910 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
24920 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
24930 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
24940 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
24950 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
24960 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
24970 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
24980 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 TH]].** ^(<dt>SQ
24990 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
249a0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f PATTERN_LENGTH</
249b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
249c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
249d0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 the pattern arg
249e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 ument to the [LI
249f0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d KE] or.** [GLOB]
24a00 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e operators.</dd>
24a10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
24a20 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
24a30 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c _NUMBER]].** ^(<
24a40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
24a50 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c VARIABLE_NUMBER<
24a60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
24a70 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 maximum index nu
24a80 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 mber of any [par
24a90 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 ameter] in an SQ
24aa0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a L statement.)^.*
24ab0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
24ac0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
24ad0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
24ae0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
24af0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
24b00 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
24b10 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 th of recursion
24b20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 for triggers.</d
24b30 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f d>)^.** </dl>.*/
24b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24b50 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 LIMIT_LENGTH
24b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
24b70 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
24b80 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
24b90 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
24ba0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
24bb0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 E_LIMIT_COLUMN
24bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
24bd0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
24be0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
24bf0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 PTH
24c00 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
24c10 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
24c20 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 ND_SELECT
24c30 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
24c40 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
24c50 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 OP
24c60 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
24c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
24c80 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 TION_ARG
24c90 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 6.#define
24ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
24cb0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 ACHED
24cc0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
24cd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 SQLITE_LIMIT_LI
24ce0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
24cf0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e H 8.#defin
24d00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
24d10 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 ARIABLE_NUMBER
24d20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
24d30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
24d40 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 TRIGGER_DEPTH
24d50 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 10../*.
24d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
24d70 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
24d80 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f atement.** KEYWO
24d90 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
24da0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
24db0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
24dc0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 n SQL query, it
24dd0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f must first be co
24de0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 mpiled into a by
24df0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 te-code.** progr
24e00 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 am using one of
24e10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
24e20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
24e30 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
24e40 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
24e50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
24e60 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
24e70 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
24e80 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
24e90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
24ea0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 3_open_v2()] or.
24eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
24ec0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 16()]. The data
24ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
24ee0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 must not have be
24ef0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a en closed..**.**
24f00 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
24f10 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
24f20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
24f30 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
24f40 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
24f50 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
24f60 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
24f70 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
24f80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
24f90 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
24fa0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
24fb0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
24fc0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
24fd0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
24fe0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
24ff0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 **.** ^If the nB
25000 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 yte argument is
25010 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 less than zero,
25020 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 then zSql is rea
25030 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 d up to the.** f
25040 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
25050 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 ator. ^If nByte
25060 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
25070 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 then it is the
25080 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 maximum.** numbe
25090 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 r of bytes read
250a0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 from zSql. ^Wh
250b0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d en nByte is non-
250c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a negative, the.**
250d0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 zSql string end
250e0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 s at either the
250f0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 first '\000' or
25100 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 '\u0000' charact
25110 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 er or.** the nBy
25120 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 te-th byte, whic
25130 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
25140 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 t. If the caller
25150 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 knows.** that t
25160 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
25170 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
25180 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 ated, then there
25190 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 is a small.** p
251a0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
251b0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 tage to be gaine
251c0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 d by passing an
251d0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
251e0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c that.** is equal
251f0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f to the number o
25200 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
25210 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
25220 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
25230 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
25240 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 or bytes as this
25250 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 saves SQLite fr
25260 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 om having to.**
25270 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 make a copy of t
25280 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e he input string.
25290 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 .**.** ^If pzTai
252a0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 l is not NULL th
252b0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 en *pzTail is ma
252c0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 de to point to t
252d0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a he first byte.**
252e0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 past the end of
252f0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 the first SQL s
25300 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
25310 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
25320 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c s only.** compil
25330 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 e the first stat
25340 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 ement in zSql, s
25350 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 o *pzTail is lef
25360 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a t pointing to.**
25370 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e what remains un
25380 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 compiled..**.**
25390 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 ^*ppStmt is left
253a0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 pointing to a c
253b0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 ompiled [prepare
253c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
253d0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 t can be.** exec
253e0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 uted using [sqli
253f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 te3_step()]. ^I
25400 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 f there is an er
25410 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 ror, *ppStmt is
25420 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 set.** to NULL.
25430 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 ^If the input t
25440 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 ext contains no
25450 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 SQL (if the inpu
25460 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a t is an empty.**
25470 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d string or a com
25480 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 ment) then *ppSt
25490 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c mt is set to NUL
254a0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e L..** The callin
254b0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 g procedure is r
254c0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 esponsible for d
254d0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 eleting the comp
254e0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 iled.** SQL stat
254f0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
25500 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
25510 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 after it has fi
25520 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a nished with it..
25530 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f ** ppStmt may no
25540 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a t be NULL..**.**
25550 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 ^On success, th
25560 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
25570 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f e() family of ro
25580 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
25590 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 QLITE_OK];.** ot
255a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
255b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
255c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
255d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
255e0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 2() and sqlite3_
255f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 prepare16_v2() i
25600 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a nterfaces are.**
25610 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
25620 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d all new program
25630 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 s. The two older
25640 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
25650 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 retained.** for
25660 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
25670 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 ibility, but the
25680 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 ir use is discou
25690 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 raged..** ^In th
256a0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
256b0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 s, the prepared
256c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 statement.** tha
256d0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 t is returned (t
256e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
256f0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 ] object) contai
25700 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
25710 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c .** original SQL
25720 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 text. This caus
25730 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f es the [sqlite3_
25740 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 step()] interfac
25750 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 e to.** behave d
25760 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 ifferently in th
25770 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ree ways:.**.**
25780 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 <ol>.** <li>.**
25790 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 ^If the database
257a0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c schema changes,
257b0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 instead of retu
257c0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 rning [SQLITE_SC
257d0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 HEMA] as it.** a
257e0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f lways used to do
257f0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
25800 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 )] will automati
25810 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 cally recompile
25820 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 the SQL.** state
25830 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 ment and try to
25840 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 run it again. As
25850 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 many as [SQLITE
25860 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 _MAX_SCHEMA_RETR
25870 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 Y].** retries wi
25880 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 ll occur before
25890 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 sqlite3_step() g
258a0 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 ives up and retu
258b0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a rns an error..**
258c0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
258d0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 >.** ^When an er
258e0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c ror occurs, [sql
258f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
25900 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 l return one of
25910 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 the detailed.**
25920 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 [error codes] or
25930 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
25940 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c codes]. ^The l
25950 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 egacy behavior w
25960 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 as that.** [sqli
25970 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c te3_step()] woul
25980 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 d only return a
25990 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f generic [SQLITE_
259a0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f ERROR] result co
259b0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 de.** and the ap
259c0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 plication would
259d0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 have to make a s
259e0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 econd call to [s
259f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a qlite3_reset()].
25a00 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 ** in order to f
25a10 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 ind the underlyi
25a20 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 ng cause of the
25a30 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 problem. With th
25a40 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a e "v2" prepare.*
25a50 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 * interfaces, th
25a60 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 e underlying rea
25a70 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f son for the erro
25a80 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d r is returned im
25a90 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f mediately..** </
25aa0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a li>.**.** <li>.*
25ab0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 * ^If the specif
25ac0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 ic value bound t
25ad0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 o [parameter | h
25ae0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 ost parameter] i
25af0 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 n the .** WHERE
25b00 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 clause might inf
25b10 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 luence the choic
25b20 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 e of query plan
25b30 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c for a statement,
25b40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 .** then the sta
25b50 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 tement will be a
25b60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 utomatically rec
25b70 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 ompiled, as if t
25b80 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a here had been .*
25b90 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 * a schema chang
25ba0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 e, on the first
25bb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
25bc0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 ] call following
25bd0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 any change.** t
25be0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 o the [sqlite3_b
25bf0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 ind_text | bindi
25c00 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 ngs] of that [pa
25c10 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 rameter]. .** ^T
25c20 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 he specific valu
25c30 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 e of WHERE-claus
25c40 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 e [parameter] mi
25c50 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 ght influence th
25c60 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 e .** choice of
25c70 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 query plan if th
25c80 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 e parameter is t
25c90 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 he left-hand sid
25ca0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a e of a [LIKE].**
25cb0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 or [GLOB] opera
25cc0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 tor or if the pa
25cd0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 rameter is compa
25ce0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 red to an indexe
25cf0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 d column.** and
25d00 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 the [SQLITE_ENAB
25d10 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c LE_STAT3] compil
25d20 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
25d30 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 enabled..** the
25d40 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f .** </li>.** </
25d50 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ol>.*/.SQLITE_AP
25d60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 I int sqlite3_pr
25d70 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 epare(. sqlite3
25d80 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
25d90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
25da0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
25db0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
25dc0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
25dd0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
25de0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
25df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
25e00 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
25e10 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
25e20 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
25e30 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
25e40 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
25e50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
25e60 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
25e70 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
25e80 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
25e90 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
25ea0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
25eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
25ec0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 are_v2(. sqlite
25ed0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
25ee0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
25ef0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
25f00 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
25f10 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
25f20 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
25f30 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
25f40 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
25f50 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
25f60 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
25f70 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
25f80 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
25f90 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
25fa0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
25fb0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
25fc0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
25fd0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
25fe0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
25ff0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
26000 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 int sqlite3_pre
26010 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 pare16(. sqlite
26020 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
26030 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
26040 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
26050 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
26060 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
26070 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
26080 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
26090 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
260a0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
260b0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
260c0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
260d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
260e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
260f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
26100 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
26110 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
26120 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
26130 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
26140 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
26150 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 I int sqlite3_pr
26160 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 epare16_v2(. sq
26170 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
26180 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
26190 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
261a0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
261b0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
261c0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
261d0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
261e0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
261f0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
26200 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
26210 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
26220 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
26230 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
26240 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
26250 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
26260 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
26270 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
26280 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
26290 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a zSql */.);../*.*
262a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 * CAPI3REF: Retr
262b0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 ieving Statement
262c0 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 SQL.**.** ^This
262d0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
262e0 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 e used to retrie
262f0 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 ve a saved copy
26300 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a of the original.
26310 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 ** SQL text used
26320 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 to create a [pr
26330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26340 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d ] if that statem
26350 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 ent was.** compi
26360 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 led using either
26370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
26380 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
26390 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
263a0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
263b0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
263c0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 qlite3_sql(sqlit
263d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
263e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
263f0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
26400 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
26410 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 Writes The Datab
26420 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ase.**.** ^The s
26430 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
26440 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 only(X) interfac
26450 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
26460 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 non-zero) if.**
26470 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 and only if the
26480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26490 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 ent] X makes no
264a0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 direct changes t
264b0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 o.** the content
264c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
264d0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 file..**.** Not
264e0 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 e that [applicat
264f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
26500 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a functions] or.**
26510 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 [virtual tables
26520 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 ] might change t
26530 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 he database indi
26540 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 rectly as a side
26550 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 effect. .** ^(
26560 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 For example, if
26570 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 an application d
26580 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f efines a functio
26590 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 n "eval()" that
265a0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 .** calls [sqlit
265b0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e e3_exec()], then
265c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
265d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 QL statement wou
265e0 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 ld.** change the
265f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
26600 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 hrough side-effe
26610 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 cts:.**.** <bloc
26620 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
26630 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 SELECT eval('
26640 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 DELETE FROM t1')
26650 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 FROM t2;.** </p
26660 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
26670 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 .**.** But becau
26680 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 se the [SELECT]
26690 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
266a0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ot change the da
266b0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 tabase file.** d
266c0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 irectly, sqlite3
266d0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
266e0 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 would still ret
266f0 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a urn true.)^.**.*
26700 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 * ^Transaction c
26710 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 ontrol statement
26720 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e s such as [BEGIN
26730 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f ], [COMMIT], [RO
26740 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 LLBACK],.** [SAV
26750 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 EPOINT], and [RE
26760 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c LEASE] cause sql
26770 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
26780 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 ly() to return t
26790 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 rue,.** since th
267a0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 e statements the
267b0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 mselves do not a
267c0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 ctually modify t
267d0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a he database but.
267e0 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 ** rather they c
267f0 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e ontrol the timin
26800 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 g of when other
26810 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 statements modif
26820 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 y the .** databa
26830 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 se. ^The [ATTAC
26840 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 H] and [DETACH]
26850 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 statements also
26860 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 cause.** sqlite3
26870 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
26880 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 to return true
26890 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f since, while tho
268a0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a se statements.**
268b0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 change the conf
268c0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 iguration of a d
268d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
268e0 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 on, they do not
268f0 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 make .** changes
26900 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 to the content
26910 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
26920 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a files on disk..*
26930 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
26940 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
26950 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 adonly(sqlite3_s
26960 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
26970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
26980 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 termine If A Pre
26990 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
269a0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a Has Been Reset.*
269b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
269c0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 3_stmt_busy(S) i
269d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
269e0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 true (non-zero)
269f0 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 if the.** [prep
26a00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
26a10 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 S has been stepp
26a20 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 ed at least once
26a30 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
26a40 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 te3_step(S)] but
26a50 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 has not run to
26a60 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f completion and/o
26a70 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 r has not .** be
26a80 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b en reset using [
26a90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
26aa0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
26ab0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a _stmt_busy(S).**
26ac0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
26ad0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 ns false if S is
26ae0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
26af0 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 If S is not a
26b00 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
26b10 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f and is not a po
26b20 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 inter to a valid
26b30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26b40 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c ment].** object,
26b50 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
26b60 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 or is undefined
26b70 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 and probably und
26b80 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 esirable..**.**
26b90 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
26ba0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f an be used in co
26bb0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 mbination [sqlit
26bc0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a e3_next_stmt()].
26bd0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c ** to locate all
26be0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
26bf0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 ents associated
26c00 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 with a database
26c10 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 .** connection t
26c20 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 hat are in need
26c30 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 of being reset.
26c40 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 This can be use
26c50 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c d,.** for exampl
26c60 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 e, in diagnostic
26c70 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 routines to sea
26c80 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 rch for prepared
26c90 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 .** statements
26ca0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 that are holding
26cb0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f a transaction o
26cc0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 pen..*/.SQLITE_A
26cd0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 PI int sqlite3_s
26ce0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 tmt_busy(sqlite3
26cf0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
26d00 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 CAPI3REF: Dynami
26d10 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 cally Typed Valu
26d20 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 e Object.** KEYW
26d30 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 ORDS: {protected
26d40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 sqlite3_value}
26d50 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c {unprotected sql
26d60 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a ite3_value}.**.*
26d70 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 * SQLite uses th
26d80 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
26d90 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 object to repres
26da0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a ent all values.*
26db0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 * that can be st
26dc0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 ored in a databa
26dd0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 se table. SQLite
26de0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 uses dynamic ty
26df0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ping.** for the
26e00 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 values it stores
26e10 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 . ^Values store
26e20 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c d in sqlite3_val
26e30 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 ue objects.** ca
26e40 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 n be integers, f
26e50 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
26e60 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 lues, strings, B
26e70 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a LOBs, or NULL..*
26e80 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f *.** An sqlite3_
26e90 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 value object may
26ea0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 be either "prot
26eb0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f ected" or "unpro
26ec0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 tected"..** Some
26ed0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 interfaces requ
26ee0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 ire a protected
26ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 sqlite3_value.
26f00 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 Other interfaces
26f10 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 .** will accept
26f20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 either a protect
26f30 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 ed or an unprote
26f40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
26f50 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 ue..** Every int
26f60 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 erface that acce
26f70 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 pts sqlite3_valu
26f80 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 e arguments spec
26f90 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 ifies.** whether
26fa0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 or not it requi
26fb0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 res a protected
26fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
26fd0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 *.** The terms "
26fe0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 protected" and "
26ff0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 unprotected" ref
27000 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 er to whether or
27010 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 not.** a mutex
27020 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 is held. An int
27030 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 ernal mutex is h
27040 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 eld for a protec
27050 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
27060 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 alue object but
27070 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 no mutex is held
27080 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 for an unprotec
27090 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
270a0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 alue object. If
270b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
270c0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 led to be single
270d0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 -threaded.** (wi
270e0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 th [SQLITE_THREA
270f0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 DSAFE=0] and wit
27100 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 h [sqlite3_threa
27110 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 dsafe()] returni
27120 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 ng 0).** or if S
27130 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 QLite is run in
27140 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d one of reduced m
27150 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b utex modes .** [
27160 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
27170 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b NGLETHREAD] or [
27180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
27190 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 LTITHREAD].** th
271a0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 en there is no d
271b0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
271c0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
271d0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
271e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
271f0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 jects and they c
27200 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 an be used inter
27210 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 changeably. How
27220 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 ever,.** for max
27230 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 imum code portab
27240 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f ility it is reco
27250 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
27260 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 lications.** sti
27270 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 ll make the dist
27280 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 inction between
27290 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
272a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
272b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
272c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 ts even when not
272d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 strictly requir
272e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
272f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
27300 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 ects that are pa
27310 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 ssed as paramete
27320 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 rs into the.** i
27330 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
27340 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
27350 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
27360 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 ons] are protect
27370 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ed..** ^The sqli
27380 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
27390 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
273a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
273b0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 value()] is unpr
273c0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 otected..** Unpr
273d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
273e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 value objects ma
273f0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
27400 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ith.** [sqlite3_
27410 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 result_value()]
27420 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
27430 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 d_value()]..** T
27440 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
27450 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 e_blob | sqlite3
27460 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 _value_type()] f
27470 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 amily of.** inte
27480 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 rfaces require p
27490 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
274a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a _value objects..
274b0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
274c0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 t Mem sqlite3_va
274d0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lue;../*.** CAPI
274e0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 3REF: SQL Functi
274f0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 on Context Objec
27500 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 t.**.** The cont
27510 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 ext in which an
27520 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 SQL function exe
27530 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 cutes is stored
27540 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 in an.** sqlite3
27550 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e _context object.
27560 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ^A pointer to
27570 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 an sqlite3_conte
27580 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 xt object.** is
27590 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 always first par
275a0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 ameter to [appli
275b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
275c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a QL functions]..*
275d0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
275e0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
275f0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
27600 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 ation will pass
27610 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 this.** pointer
27620 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c through into cal
27630 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ls to [sqlite3_r
27640 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 esult_int | sqli
27650 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a te3_result()],.*
27660 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 * [sqlite3_aggre
27670 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c gate_context()],
27680 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
27690 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ata()],.** [sqli
276a0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
276b0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 andle()], [sqlit
276c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
276d0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 ],.** and/or [sq
276e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
276f0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 a()]..*/.typedef
27700 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
27710 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f context sqlite3_
27720 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 context;../*.**
27730 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e CAPI3REF: Bindin
27740 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 g Values To Prep
27750 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a ared Statements.
27760 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f ** KEYWORDS: {ho
27770 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 st parameter} {h
27780 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 ost parameters}
27790 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 {host parameter
277a0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 name}.** KEYWORD
277b0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 S: {SQL paramete
277c0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 r} {SQL paramete
277d0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 rs} {parameter b
277e0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 inding}.**.** ^(
277f0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 In the SQL state
27800 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 ment text input
27810 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
27820 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 are_v2()] and it
27830 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c s variants,.** l
27840 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 iterals may be r
27850 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 eplaced by a [pa
27860 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 rameter] that ma
27870 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c tches one of fol
27880 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 lowing.** templa
27890 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a tes:.**.** <ul>.
278a0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c ** <li> ?.** <l
278b0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e i> ?NNN.** <li>
278c0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 :VVV.** <li>
278d0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 @VVV.** <li> $V
278e0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VV.** </ul>.**.*
278f0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 * In the templat
27900 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 es above, NNN re
27910 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 presents an inte
27920 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 ger literal,.**
27930 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e and VVV represen
27940 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 ts an alphanumer
27950 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e ic identifier.)^
27960 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 ^The values of
27970 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 these.** parame
27980 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 ters (also calle
27990 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 d "host paramete
279a0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c r names" or "SQL
279b0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a parameters").**
279c0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e can be set usin
279d0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
279e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
279f0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a defined here..**
27a00 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
27a10 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
27a20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
27a30 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 routines is alwa
27a40 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ys.** a pointer
27a50 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
27a60 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
27a70 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 urned from.** [s
27a80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
27a90 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 2()] or its vari
27aa0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ants..**.** ^The
27ab0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
27ac0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
27ad0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
27ae0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
27af0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 ^The leftmost S
27b00 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 QL parameter has
27b10 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 an index of 1.
27b20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 ^When the same
27b30 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 named.** SQL par
27b40 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d ameter is used m
27b50 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 ore than once, s
27b60 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
27b70 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e uent.** occurren
27b80 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d ces have the sam
27b90 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 e index as the f
27ba0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e irst occurrence.
27bb0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 .** ^The index f
27bc0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 or named paramet
27bd0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 ers can be looke
27be0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a d up using the.*
27bf0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
27c00 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
27c10 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 )] API if desire
27c20 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a d. ^The index.*
27c30 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 * for "?NNN" par
27c40 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 ameters is the v
27c50 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 alue of NNN..**
27c60 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d ^The NNN value m
27c70 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
27c80 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 and the [sqlite
27c90 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 3_limit()].** pa
27ca0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f rameter [SQLITE_
27cb0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
27cc0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 UMBER] (default
27cd0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a value: 999)..**.
27ce0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 ** ^The third ar
27cf0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 gument is the va
27d00 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 lue to bind to t
27d10 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
27d20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
27d30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
27d40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 te3_bind_text()
27d50 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
27d60 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 text16().** or s
27d70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
27d80 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
27d90 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f nter then the fo
27da0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a urth parameter.*
27db0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 * is ignored and
27dc0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 the end result
27dd0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 is the same as s
27de0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
27df0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 ()..**.** ^(In t
27e00 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 hose routines th
27e10 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 at have a fourth
27e20 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 argument, its v
27e30 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
27e40 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
27e50 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e n the parameter.
27e60 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 To be clear: t
27e70 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a he value is the.
27e80 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e ** number of <u>
27e90 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 bytes</u> in the
27ea0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 value, not the
27eb0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
27ec0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 ters.)^.** ^If t
27ed0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
27ee0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
27ef0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
27f00 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
27f10 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 6().** is negati
27f20 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e ve, then the len
27f30 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
27f40 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 g is.** the numb
27f50 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 er of bytes up t
27f60 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
27f70 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 terminator..**
27f80 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
27f90 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
27fa0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
27fb0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
27fc0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 .** the behavior
27fd0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
27fe0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 * If a non-negat
27ff0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d ive fourth param
28000 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 eter is provided
28010 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
28020 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _text().** or sq
28030 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
28040 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 6() then that pa
28050 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
28060 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a the byte offset.
28070 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c ** where the NUL
28080 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c terminator woul
28090 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 d occur assuming
280a0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 the string were
280b0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 NUL.** terminat
280c0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 ed. If any NUL
280d0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 characters occur
280e0 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 at byte offsets
280f0 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 less than .** t
28100 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
28110 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
28120 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
28130 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 ing string value
28140 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e will.** contain
28150 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 embedded NULs.
28160 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 The result of e
28170 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c xpressions invol
28180 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 ving strings.**
28190 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 with embedded NU
281a0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e Ls is undefined.
281b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 .**.** ^The fift
281c0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
281d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
281e0 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ), sqlite3_bind_
281f0 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 text(), and.** s
28200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
28210 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 16() is a destru
28220 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 ctor used to dis
28230 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
28240 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 or.** string af
28250 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 ter SQLite has f
28260 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
28270 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f ^The destructo
28280 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 r is called.** t
28290 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
282a0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 BLOB or string
282b0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c even if the call
282c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
282d0 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 _blob(),.** sqli
282e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c te3_bind_text(),
282f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
28300 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e _text16() fails.
28310 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 .** ^If the fi
28320 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
28330 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
28340 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
28350 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
28360 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
28370 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
28380 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
28390 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
283a0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
283b0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
283c0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
283d0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
283e0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
283f0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
28400 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
28410 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
28420 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
28430 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
28440 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
28450 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
28460 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
28470 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
28480 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
28490 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 routine binds a
284a0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 BLOB of length
284b0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c N that.** is fil
284c0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e led with zeroes.
284d0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 ^A zeroblob us
284e0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e es a fixed amoun
284f0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 t of memory.** (
28500 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 just an integer
28510 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 to hold its size
28520 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 ) while it is be
28530 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a ing processed..*
28540 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 * Zeroblobs are
28550 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 intended to serv
28560 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 e as placeholder
28570 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 s for BLOBs whos
28580 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 e.** content is
28590 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 later written us
285a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
285b0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
285c0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
285d0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e ] routines..** ^
285e0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
285f0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
28600 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
28610 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
28620 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
28630 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
28640 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
28650 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
28660 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
28670 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
28680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
28690 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
286a0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
286b0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
286c0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
286d0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
286e0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
286f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
28700 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
28710 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
28720 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
28730 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
28740 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
28750 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
28760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28770 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
28780 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
28790 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
287a0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
287b0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
287c0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
287d0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
287e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
287f0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
28800 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
28810 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
28820 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
28830 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
28840 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
28850 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
28860 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
28870 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
28880 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
28890 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
288a0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 ^[SQLITE_RANGE]
288b0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
288c0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
288d0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
288e0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 range. ^[SQLITE
288f0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 _NOMEM] is retur
28900 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 ned if malloc()
28910 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fails..**.** See
28920 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
28930 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
28940 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ount()],.** [sql
28950 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
28960 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
28970 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
28980 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
28990 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
289a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
289b0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
289c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
289d0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
289e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
289f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
28a00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
28a10 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
28a20 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
28a30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
28a40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 qlite3_bind_int(
28a50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
28a60 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 nt, int);.SQLITE
28a70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
28a80 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
28a90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
28aa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
28ab0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
28ac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
28ad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
28ae0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
28af0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
28b00 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
28b10 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
28b20 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 char*, int n, v
28b30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
28b40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
28b50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
28b60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
28b70 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
28b80 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
28b90 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
28ba0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
28bb0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 _bind_value(sqli
28bc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
28bd0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
28be0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
28bf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
28c00 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
28c10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
28c20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
28c30 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
28c40 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
28c50 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f s.**.** ^This ro
28c60 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 utine can be use
28c70 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
28c80 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 mber of [SQL par
28c90 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 ameters].** in a
28ca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
28cb0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 ment]. SQL para
28cc0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e meters are token
28cd0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d s of the.** form
28ce0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a "?", "?NNN", ":
28cf0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 AAA", "$AAA", or
28d00 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 "@AAA" that ser
28d10 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f ve as.** placeho
28d20 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 lders for values
28d30 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 that are [sqlit
28d40 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
28d50 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 ound].** to the
28d60 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 parameters at a
28d70 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a later time..**.*
28d80 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
28d90 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e actually return
28da0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
28db0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 he largest (righ
28dc0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 tmost).** parame
28dd0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 ter. For all for
28de0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 ms except ?NNN,
28df0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 this will corres
28e00 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e pond to the.** n
28e10 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 umber of unique
28e20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 parameters. If
28e30 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
28e40 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 e ?NNN form are
28e50 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d used,.** there m
28e60 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 ay be gaps in th
28e70 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 e list.)^.**.**
28e80 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
28e90 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
28ea0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
28eb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
28ec0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
28ed0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
28ee0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
28ef0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
28f00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
28f10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
28f20 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ter_count(sqlite
28f30 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
28f40 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
28f50 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 Of A Host Parame
28f60 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ter.**.** ^The s
28f70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
28f80 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 meter_name(P,N)
28f90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
28fa0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 s.** the name of
28fb0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 the N-th [SQL p
28fc0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
28fd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
28fe0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 ment] P..** ^(SQ
28ff0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
29000 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
29010 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
29020 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
29030 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
29040 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
29050 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
29060 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
29070 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
29080 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
29090 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
290a0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
290b0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
290c0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
290d0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
290e0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 e.)^.** ^Paramet
290f0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
29100 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f "?" without a fo
29110 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 llowing integer
29120 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 have no name.**
29130 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 and are referred
29140 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 to as "nameless
29150 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 " or "anonymous
29160 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a parameters"..**.
29170 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f ** ^The first ho
29180 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 st parameter has
29190 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 an index of 1,
291a0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 not 0..**.** ^If
291b0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 the value N is
291c0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
291d0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 if the N-th para
291e0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 meter is.** name
291f0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 less, then NULL
29200 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 is returned. ^T
29210 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
29220 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 ng is.** always
29230 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e in UTF-8 encodin
29240 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 g even if the na
29250 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 med parameter wa
29260 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 s.** originally
29270 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 specified as UTF
29280 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f -16 in [sqlite3_
29290 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a prepare16()] or.
292a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
292b0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
292c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
292d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
292e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
292f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
29300 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
29310 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
29320 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
29330 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
29340 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
29350 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
29360 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
29370 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
29380 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
29390 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
293a0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
293b0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
293c0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 e.**.** ^Return
293d0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 the index of an
293e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 SQL parameter gi
293f0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e ven its name. ^
29400 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c The.** index val
29410 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 ue returned is s
29420 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 uitable for use
29430 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
29440 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
29450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
29460 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
29470 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 . ^A zero.** is
29480 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 returned if no
29490 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 matching paramet
294a0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 er is found. ^T
294b0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
294c0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
294d0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
294e0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
294f0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
29500 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
29510 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
29520 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
29530 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
29540 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
29550 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
29560 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
29570 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
29580 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
29590 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
295a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
295b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
295c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
295d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
295e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
295f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
29600 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
29610 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
29620 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
29630 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
29640 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d Statement.**.*
29650 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 * ^Contrary to t
29660 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
29670 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
29680 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
29690 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
296a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
296b0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
296c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
296d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 ement]..** ^Use
296e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 this routine to
296f0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 reset all host p
29700 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c arameters to NUL
29710 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 L..*/.SQLITE_API
29720 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 int sqlite3_cle
29730 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 ar_bindings(sqli
29740 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
29750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
29760 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 ber Of Columns I
29770 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a n A Result Set.*
29780 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
29790 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
297a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
297b0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
297c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
297d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 d statement]. ^T
297e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
297f0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 rns 0 if pStmt i
29800 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 s an SQL.** stat
29810 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 ement that does
29820 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 not return data
29830 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 (for example an
29840 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a [UPDATE])..**.**
29850 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
29860 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
29870 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
29880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
29890 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 mn_count(sqlite3
298a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
298b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
298c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 Column Names In
298d0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a A Result Set.**.
298e0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
298f0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 es return the na
29900 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 me assigned to a
29910 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 particular colu
29920 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 mn.** in the res
29930 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
29940 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
29950 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ^The sqlite3_c
29960 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 olumn_name().**
29970 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
29980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
29990 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
299a0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
299b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
299c0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 umn_name16() ret
299d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
299e0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
299f0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
29a00 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 ring. ^The firs
29a10 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
29a20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
29a30 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
29a40 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
29a50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
29a60 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 t. ^The second p
29a70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
29a80 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 ** column number
29a90 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 . ^The leftmost
29aa0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 column is numbe
29ab0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 r 0..**.** ^The
29ac0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
29ad0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
29ae0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
29af0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
29b00 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 ement].** is des
29b10 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
29b20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
29b30 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
29b40 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
29b50 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
29b60 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
29b70 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
29b80 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
29b90 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
29ba0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
29bb0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 next call to.**
29bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
29bd0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ame() or sqlite3
29be0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
29bf0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c on the same col
29c00 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 umn..**.** ^If s
29c10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
29c20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 fails during the
29c30 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 processing of e
29c40 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a ither routine.**
29c50 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 (for example du
29c60 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f ring a conversio
29c70 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 n from UTF-8 to
29c80 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a UTF-16) then a.*
29c90 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
29ca0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
29cb0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 * ^The name of a
29cc0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
29cd0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
29ce0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 he "AS" clause f
29cf0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d or.** that colum
29d00 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 n, if there is a
29d10 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 n AS clause. If
29d20 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 there is no AS
29d30 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 clause.** then t
29d40 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
29d50 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 olumn is unspeci
29d60 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 fied and may cha
29d70 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 nge from.** one
29d80 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
29d90 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
29da0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
29db0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
29dc0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c _column_name(sql
29dd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
29de0 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 N);.SQLITE_API c
29df0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
29e00 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
29e10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
29e20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int N);../*.** C
29e30 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 API3REF: Source
29e40 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 Of Data In A Que
29e50 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 ry Result.**.**
29e60 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
29e70 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 provide a means
29e80 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 to determine the
29e90 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
29ea0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 , and.** table c
29eb0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 olumn that is th
29ec0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 e origin of a pa
29ed0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 rticular result
29ee0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 column in.** [SE
29ef0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
29f00 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
29f10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 the database or
29f20 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
29f30 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
29f40 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 as.** either a
29f50 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
29f60 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 string. ^The _d
29f70 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
29f80 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
29f90 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
29fa0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
29fb0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
29fc0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
29fd0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
29fe0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
29ff0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
2a000 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
2a010 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 string is valid
2a020 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 until the [prepa
2a030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
2a040 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 s destroyed.** u
2a050 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
2a060 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
2a070 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 il the statement
2a080 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
2a090 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 y.** reprepared
2a0a0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c by the first cal
2a0b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2a0c0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 ep()] for a part
2a0d0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 icular run.** or
2a0e0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 until the same
2a0f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 information is r
2a100 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 equested.** agai
2a110 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 n in a different
2a120 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
2a130 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 ^The names retu
2a140 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 rned are the ori
2a150 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 ginal un-aliased
2a160 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
2a170 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
2a180 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a , and column..**
2a190 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
2a1a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 rgument to these
2a1b0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 interfaces is a
2a1c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2a1d0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 ment]..** ^These
2a1e0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
2a1f0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
2a200 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 out the Nth resu
2a210 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e lt column return
2a220 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 ed by.** the sta
2a230 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 tement, where N
2a240 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 is the second fu
2a250 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
2a260 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f .** ^The left-mo
2a270 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c st column is col
2a280 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 umn 0 for these
2a290 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
2a2a0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2a2b0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 mn returned by t
2a2c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
2a2d0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 an expression or
2a2e0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 .** subquery and
2a2f0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e is not a column
2a300 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c value, then all
2a310 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
2a320 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 ons return.** NU
2a330 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 LL. ^These rout
2a340 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 ine might also r
2a350 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 eturn NULL if a
2a360 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
2a370 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 n error.** occur
2a380 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 s. ^Otherwise,
2a390 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
2a3a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 name of the atta
2a3b0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 ched database, t
2a3c0 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 able,.** or colu
2a3d0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
2a3e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
2a3f0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
2a400 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 **.** ^As with a
2a410 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ll other SQLite
2a420 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 APIs, those whos
2a430 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 e names end with
2a440 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
2a450 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
2a460 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f trings and the o
2a470 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
2a480 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a eturn UTF-8..**.
2a490 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 ** ^These APIs a
2a4a0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
2a4b0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
2a4c0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
2a4d0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
2a4e0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
2a4f0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
2a500 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e rocessor symbol.
2a510 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
2a520 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
2a530 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f ll one or more o
2a540 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2a550 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d against the sam
2a560 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 e.** prepared st
2a570 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 atement and colu
2a580 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 mn at the same t
2a590 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
2a5a0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 ults are.** unde
2a5b0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
2a5c0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
2a5d0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
2a5e0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 more.** [sqlite3
2a5f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
2a600 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
2a610 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
2a620 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 es].** for the s
2a630 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ame [prepared st
2a640 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 atement] and res
2a650 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 ult column.** at
2a660 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
2a670 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
2a680 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2a690 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
2a6a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2a6b0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
2a6c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2a6d0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
2a6e0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2a6f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2a700 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
2a710 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2a720 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2a730 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
2a740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
2a750 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2a760 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
2a770 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2a780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2a790 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 able_name16(sqli
2a7a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2a7b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2a7c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2a7d0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d olumn_origin_nam
2a7e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2a7f0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2a800 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
2a810 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
2a820 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 in_name16(sqlite
2a830 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
2a840 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2a850 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 eclared Datatype
2a860 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 Of A Query Resu
2a870 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 lt.**.** ^(The f
2a880 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
2a890 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
2a8a0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 atement]..** If
2a8b0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 this statement i
2a8c0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 s a [SELECT] sta
2a8d0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e tement and the N
2a8e0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
2a8f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 .** returned res
2a900 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 ult set of that
2a910 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 [SELECT] is a ta
2a920 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 ble column (not
2a930 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
2a940 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 or subquery) th
2a950 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 en the declared
2a960 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
2a970 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 e.** column is r
2a980 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 eturned.)^ ^If
2a990 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
2a9a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
2a9b0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 is an.** expres
2a9c0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2a9d0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f , then a NULL po
2a9e0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
2a9f0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 d..** ^The retur
2aa00 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c ned string is al
2aa10 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 ways UTF-8 encod
2aa20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 ed..**.** ^(For
2aa30 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 example, given t
2aa40 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
2aa50 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 ma:.**.** CREATE
2aa60 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 TABLE t1(c1 VAR
2aa70 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 IANT);.**.** and
2aa80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
2aa90 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
2aaa0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 ompiled:.**.** S
2aab0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 ELECT c1 + 1, c1
2aac0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 FROM t1;.**.**
2aad0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 this routine wou
2aae0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 ld return the st
2aaf0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 ring "VARIANT" f
2ab00 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 or the second re
2ab10 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 sult.** column (
2ab20 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c i==1), and a NUL
2ab30 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 L pointer for th
2ab40 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 e first result c
2ab50 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a olumn (i==0).)^.
2ab60 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
2ab70 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 es dynamic run-t
2ab80 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f ime typing. ^So
2ab90 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 just because a
2aba0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 column.** is dec
2abb0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e lared to contain
2abc0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 a particular ty
2abd0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e pe does not mean
2abe0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 that the.** dat
2abf0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 a stored in that
2ac00 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 column is of th
2ac10 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e e declared type.
2ac20 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 SQLite is.** s
2ac30 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 trongly typed, b
2ac40 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 ut the typing is
2ac50 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 dynamic not sta
2ac60 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 tic. ^Type.** i
2ac70 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
2ac80 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c h individual val
2ac90 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 ues, not with th
2aca0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 e containers.**
2acb0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f used to hold tho
2acc0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 se values..*/.SQ
2acd0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2ace0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
2acf0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c umn_decltype(sql
2ad00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2ad10 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2ad20 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
2ad30 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
2ad40 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2ad50 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
2ad60 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
2ad70 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
2ad80 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
2ad90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ada0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
2adb0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
2adc0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
2add0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2ade0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2adf0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
2ae00 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
2ae10 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
2ae20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2ae30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
2ae40 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
2ae50 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
2ae60 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
2ae70 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
2ae80 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
2ae90 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
2aea0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
2aeb0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
2aec0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2aed0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
2aee0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
2aef0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
2af00 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
2af10 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
2af20 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
2af30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2af40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2af50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
2af60 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
2af70 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
2af80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2af90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2afa0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
2afb0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
2afc0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
2afd0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
2afe0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
2aff0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
2b000 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
2b010 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
2b020 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
2b030 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 ed..**.** ^In th
2b040 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
2b050 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ce, the return v
2b060 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 alue will be eit
2b070 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 her [SQLITE_BUSY
2b080 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ],.** [SQLITE_DO
2b090 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 NE], [SQLITE_ROW
2b0a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ], [SQLITE_ERROR
2b0b0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
2b0c0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 SUSE]..** ^With
2b0d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2b0e0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
2b0f0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
2b100 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
2b110 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
2b120 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
2b130 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
2b140 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 ** ^[SQLITE_BUSY
2b150 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2b160 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2b170 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 was unable to a
2b180 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 cquire the.** da
2b190 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 tabase locks it
2b1a0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 needs to do its
2b1b0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 job. ^If the st
2b1c0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
2b1d0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
2b1e0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
2b1f0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
2b200 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
2b210 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
2b220 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
2b230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2b240 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
2b250 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
2b260 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 n an.** explicit
2b270 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
2b280 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
2b290 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
2b2a0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
2b2b0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
2b2c0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d * ^[SQLITE_DONE]
2b2d0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
2b2e0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 statement has fi
2b2f0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
2b300 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
2b310 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
2b320 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
2b330 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 called again on
2b340 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 this virtual.**
2b350 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 machine without
2b360 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 first calling [s
2b370 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2b380 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 to reset the vir
2b390 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
2b3a0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
2b3b0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a ial state..**.**
2b3c0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 ^If the SQL sta
2b3d0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
2b3e0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
2b3f0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
2b400 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
2b410 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
2b420 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
2b430 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
2b440 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
2b450 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
2b460 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
2b470 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
2b480 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
2b490 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
2b4a0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
2b4b0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
2b4c0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
2b4d0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
2b4e0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 a..**.** ^[SQLIT
2b4f0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
2b500 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
2b510 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
2b520 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
2b530 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
2b540 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
2b550 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
2b560 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
2b570 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
2b580 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
2b590 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
2b5a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2b5b0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
2b5c0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 ^With the legacy
2b5d0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f interface, a mo
2b5e0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
2b5f0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d r code (for exam
2b600 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ple,.** [SQLITE_
2b610 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c INTERRUPT], [SQL
2b620 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 ITE_SCHEMA], [SQ
2b630 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 LITE_CORRUPT], a
2b640 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 nd so forth).**
2b650 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
2b660 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
2b670 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 te3_reset()] on
2b680 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2b690 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 statement]. ^I
2b6a0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
2b6b0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 face,.** the mor
2b6c0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
2b6d0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 code is returne
2b6e0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 d directly by sq
2b6f0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a lite3_step()..**
2b700 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
2b710 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SE] means that t
2b720 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 he this routine
2b730 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 was called inapp
2b740 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 ropriately..** P
2b750 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 erhaps it was ca
2b760 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 lled on a [prepa
2b770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
2b780 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 hat has.** alrea
2b790 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 dy been [sqlite3
2b7a0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
2b7b0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 lized] or on one
2b7c0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 that had.** pre
2b7d0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
2b7e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2b7f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
2b800 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a . Or it could.*
2b810 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 * be the case th
2b820 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 at the same data
2b830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2b840 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 is being used by
2b850 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 two or.** more
2b860 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
2b870 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 ame moment in ti
2b880 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c me..**.** For al
2b890 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 l versions of SQ
2b8a0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 Lite up to and i
2b8b0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e ncluding 3.6.23.
2b8c0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 1, a call to.**
2b8d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2b8e0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 ] was required a
2b8f0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 fter sqlite3_ste
2b900 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 p() returned any
2b910 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 thing.** other t
2b920 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
2b930 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 before any subs
2b940 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
2b950 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n of.** sqlite3_
2b960 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 step(). Failure
2b970 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 to reset the pr
2b980 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b990 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
2b9a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 te3_reset()] wou
2b9b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 ld result in an
2b9c0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
2b9d0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 return from.** s
2b9e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
2b9f0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f But after versio
2ba00 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 n 3.6.23.1, sqli
2ba10 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e te3_step() began
2ba20 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c .** calling [sql
2ba30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 ite3_reset()] au
2ba40 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 tomatically in t
2ba50 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 his circumstance
2ba60 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 rather.** than
2ba70 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
2ba80 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 E_MISUSE]. This
2ba90 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 is not consider
2baa0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 ed a compatibili
2bab0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 ty.** break beca
2bac0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 use any applicat
2bad0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 ion that ever re
2bae0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 ceives an SQLITE
2baf0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a _MISUSE error.**
2bb00 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 is broken by de
2bb10 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b finition. The [
2bb20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
2bb30 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 RESET] compile-t
2bb40 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 ime option.** ca
2bb50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 n be used to res
2bb60 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 tore the legacy
2bb70 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
2bb80 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
2bb90 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
2bba0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
2bbb0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
2bbc0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
2bbd0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
2bbe0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
2bbf0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
2bc00 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
2bc10 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
2bc20 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2bc30 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
2bc40 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
2bc50 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
2bc60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2bc70 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2bc80 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
2bc90 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
2bca0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
2bcb0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
2bcc0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
2bcd0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
2bce0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
2bcf0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
2bd00 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
2bd10 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
2bd20 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
2bd30 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
2bd40 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
2bd50 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
2bd60 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
2bd70 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
2bd80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2bd90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2bda0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
2bdb0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
2bdc0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
2bdd0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
2bde0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2bdf0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
2be00 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
2be10 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
2be20 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
2be30 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
2be40 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
2be50 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
2be60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2be70 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2be80 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 d..*/.SQLITE_API
2be90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 int sqlite3_ste
2bea0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 p(sqlite3_stmt*)
2beb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2bec0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c F: Number of col
2bed0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 umns in a result
2bee0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 set.**.** ^The
2bef0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2bf00 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 nt(P) interface
2bf10 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2bf20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2bf30 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 the.** current
2bf40 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2bf50 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 t set of [prepar
2bf60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
2bf70 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 .** ^If prepared
2bf80 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 statement P doe
2bf90 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c s not have resul
2bfa0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 ts ready to retu
2bfb0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 rn.** (via calls
2bfc0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
2bfd0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 _column_int | sq
2bfe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 lite3_column_*()
2bff0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 ] of.** interfac
2c000 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 es) then sqlite3
2c010 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 _data_count(P) r
2c020 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 eturns 0..** ^Th
2c030 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2c040 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2c050 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 also returns 0 i
2c060 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f P is a NULL po
2c070 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 inter..** ^The s
2c080 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2c090 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 t(P) routine ret
2c0a0 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 urns 0 if the pr
2c0b0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a evious call to.*
2c0c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d * [sqlite3_step]
2c0d0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 (P) returned [SQ
2c0e0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 LITE_DONE]. ^Th
2c0f0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2c100 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 ount(P).** will
2c110 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 return non-zero
2c120 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c if previous call
2c130 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2c140 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a p](P) returned.*
2c150 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 * [SQLITE_ROW],
2c160 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 except in the ca
2c170 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d se of the [PRAGM
2c180 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 A incremental_va
2c190 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 cuum].** where i
2c1a0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 t always returns
2c1b0 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 zero since each
2c1c0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 step of that mu
2c1d0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 lti-step.** prag
2c1e0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c ma returns 0 col
2c1f0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a umns of data..**
2c200 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2c210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
2c220 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 unt()].*/.SQLITE
2c230 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2c240 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 _data_count(sqli
2c250 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2c260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2c270 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 F: Fundamental D
2c280 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 atatypes.** KEYW
2c290 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
2c2a0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 T.**.** ^(Every
2c2b0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 value in SQLite
2c2c0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 has one of five
2c2d0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 fundamental data
2c2e0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c types:.**.** <ul
2c2f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 >.** <li> 64-bit
2c300 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
2c310 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 ** <li> 64-bit I
2c320 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 EEE floating poi
2c330 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 nt number.** <li
2c340 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e > string.** <li>
2c350 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 BLOB.** <li> NU
2c360 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a LL.** </ul>)^.**
2c370 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
2c380 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f nts are codes fo
2c390 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 r each of those
2c3a0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 types..**.** Not
2c3b0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 e that the SQLIT
2c3c0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 E_TEXT constant
2c3d0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e was also used in
2c3e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2c3f0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 2.** for a compl
2c400 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 etely different
2c410 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 meaning. Softwa
2c420 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 re that links ag
2c430 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 ainst both.** SQ
2c440 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 Lite version 2 a
2c450 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f nd SQLite versio
2c460 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 n 3 should use S
2c470 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 QLITE3_TEXT, not
2c480 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e .** SQLITE_TEXT.
2c490 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2c4a0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 TE_INTEGER 1.#d
2c4b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f efine SQLITE_FLO
2c4c0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 AT 2.#define
2c4d0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 SQLITE_BLOB
2c4e0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
2c4f0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 _NULL 5.#ifd
2c500 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 ef SQLITE_TEXT.#
2c510 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 undef SQLITE_TE
2c520 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e XT.#else.# defin
2c530 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 e SQLITE_TEXT
2c540 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 3.#endif.#defi
2c550 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 ne SQLITE3_TEXT
2c560 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 3../*.** CAP
2c570 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 I3REF: Result Va
2c580 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 lues From A Quer
2c590 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b y.** KEYWORDS: {
2c5a0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
2c5b0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 nctions}.**.** T
2c5c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hese routines fo
2c5d0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 rm the "result s
2c5e0 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a et" interface..*
2c5f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
2c600 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
2c610 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 rmation about a
2c620 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
2c630 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
2c640 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
2c650 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 query. ^In ever
2c660 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 y case the first
2c670 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
2c680 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
2c690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2c6a0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 ment] that is be
2c6b0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 ing evaluated (t
2c6c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
2c6d0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 *].** that was r
2c6e0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 eturned from [sq
2c6f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2c700 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 ()] or one of it
2c710 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 s variants).** a
2c720 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 nd the second ar
2c730 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
2c740 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d dex of the colum
2c750 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f n for which info
2c760 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c rmation.** shoul
2c770 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e d be returned. ^
2c780 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
2c790 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
2c7a0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e t set has the in
2c7b0 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e dex 0..** ^The n
2c7c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2c7d0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 in the result c
2c7e0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 an be determined
2c7f0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
2c800 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
2c810 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 )]..**.** If the
2c820 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 SQL statement d
2c830 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c oes not currentl
2c840 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c y point to a val
2c850 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 id row, or if th
2c860 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 e.** column inde
2c870 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
2c880 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 e, the result is
2c890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
2c8a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 hese routines ma
2c8b0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 y only be called
2c8c0 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 when the most r
2c8d0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a ecent call to.**
2c8e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2c8f0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b ] has returned [
2c900 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 SQLITE_ROW] and
2c910 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 neither.** [sqli
2c920 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 te3_reset()] nor
2c930 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2c940 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 ze()] have been
2c950 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e called subsequen
2c960 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f tly..** If any o
2c970 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2c980 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 are called afte
2c990 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
2c9a0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
2c9b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
2c9c0 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 r after [sqlite3
2c9d0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
2c9e0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 urned.** somethi
2c9f0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ng other than [S
2ca00 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 QLITE_ROW], the
2ca10 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2ca20 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 fined..** If [sq
2ca30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
2ca40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2ca50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
2ca60 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 inalize()].** ar
2ca70 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 e called from a
2ca80 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
2ca90 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 while any of th
2caa0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
2cab0 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 are pending, the
2cac0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
2cad0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
2cae0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2caf0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f column_type() ro
2cb00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
2cb10 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 e.** [SQLITE_INT
2cb20 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 EGER | datatype
2cb30 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e code] for the in
2cb40 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a itial data type.
2cb50 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ** of the result
2cb60 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 column. ^The r
2cb70 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 eturned value is
2cb80 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
2cb90 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 INTEGER],.** [SQ
2cba0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 LITE_FLOAT], [SQ
2cbb0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c LITE_TEXT], [SQL
2cbc0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 ITE_BLOB], or [S
2cbd0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 QLITE_NULL]. Th
2cbe0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
2cbf0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2cc00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2cc10 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 only meaningful
2cc20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f if no type.** co
2cc30 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f nversions have o
2cc40 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 ccurred as descr
2cc50 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 ibed below. Aft
2cc60 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
2cc70 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c sion,.** the val
2cc80 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
2cc90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2cca0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 pe() is undefine
2ccb0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 d. Future.** ve
2ccc0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
2ccd0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 may change the
2cce0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
2ccf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2cd00 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 ).** following a
2cd10 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2cd20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2cd30 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
2cd40 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 or UTF-8 string
2cd50 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
2cd60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2cd70 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
2cd80 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2cd90 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
2cda0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
2cdb0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2cdc0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 t is a UTF-16 st
2cdd0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
2cde0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2cdf0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2ce00 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2ce10 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 8 and then retur
2ce20 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2ce30 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 bytes..** ^If t
2ce40 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e he result is a n
2ce50 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 umeric value the
2ce60 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2ce70 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a _bytes() uses.**
2ce80 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
2ce90 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 tf()] to convert
2cea0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 that value to a
2ceb0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e UTF-8 string an
2cec0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 d returns.** the
2ced0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2cee0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e in that string.
2cef0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2cf00 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e lt is NULL, then
2cf10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2cf20 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 bytes() returns
2cf30 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 zero..**.** ^If
2cf40 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2cf50 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 BLOB or UTF-16 s
2cf60 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 tring then the s
2cf70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2cf80 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 tes16().** routi
2cf90 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
2cfa0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
2cfb0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 n that BLOB or s
2cfc0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
2cfd0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 e result is a UT
2cfe0 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e F-8 string, then
2cff0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2d000 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 bytes16() conver
2d010 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2d020 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 to UTF-16 and t
2d030 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
2d040 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
2d050 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2d060 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 lt is a numeric
2d070 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 value then sqlit
2d080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2d090 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 6() uses.** [sql
2d0a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
2d0b0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 to convert that
2d0c0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d value to a UTF-
2d0d0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 16 string and re
2d0e0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d turns.** the num
2d0f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2d100 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 that string..**
2d110 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2d120 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c s NULL, then sql
2d130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2d140 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 s16() returns ze
2d150 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 ro..**.** ^The v
2d160 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
2d170 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
2d180 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a n_bytes()] and .
2d190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2d1a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f mn_bytes16()] do
2d1b0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 not include the
2d1c0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2d1d0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 s at the end.**
2d1e0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 of the string.
2d1f0 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 ^For clarity: th
2d200 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
2d210 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
2d220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d _column_bytes()]
2d230 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f and [sqlite3_co
2d240 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 lumn_bytes16()]
2d250 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f are the number o
2d260 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 f.** bytes in th
2d270 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 e string, not th
2d280 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
2d290 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 acters..**.** ^S
2d2a0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
2d2b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2d2c0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c n_text() and sql
2d2d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2d2e0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 16(),.** even em
2d2f0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 pty strings, are
2d300 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
2d310 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 minated. ^The r
2d320 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 eturn.** value f
2d330 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 rom sqlite3_colu
2d340 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 mn_blob() for a
2d350 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 zero-length BLOB
2d360 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2d370 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f er..**.** ^The o
2d380 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
2d390 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
2d3a0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e n_value()] is an
2d3b0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
2d3c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2d3d0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 object. An unpr
2d3e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2d3f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 value object.**
2d400 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
2d410 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 with [sqlite3_b
2d420 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ind_value()] and
2d430 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
2d440 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 _value()]..** If
2d450 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 the [unprotecte
2d460 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2d470 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
2d480 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
2d490 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
2d4a0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f is used in any o
2d4b0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 ther way, includ
2d4c0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 ing calls.** to
2d4d0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
2d4e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
2d4f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
2d500 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 lue_text()],.**
2d510 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 or [sqlite3_valu
2d520 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e e_bytes()], then
2d530 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2d540 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2d550 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
2d560 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 attempt to conv
2d570 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 ert the value wh
2d580 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e ere appropriate.
2d590 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c ^For.** exampl
2d5a0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e e, if the intern
2d5b0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
2d5c0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 n is FLOAT and a
2d5d0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 text result.**
2d5e0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 is requested, [s
2d5f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
2d600 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 )] is used inter
2d610 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d nally to perform
2d620 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 the.** conversi
2d630 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 on automatically
2d640 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 . ^(The followi
2d650 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 ng table details
2d660 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 the conversions
2d670 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 .** that are app
2d680 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lied:.**.** <blo
2d690 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
2d6a0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
2d6b0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 * <tr><th> Inter
2d6c0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e nal<br>Type <th>
2d6d0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 Requested<br>Ty
2d6e0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 pe <th> Convers
2d6f0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 ion.**.** <tr><t
2d700 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
2d710 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2d720 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c Result is 0.** <
2d730 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2d740 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
2d750 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
2d760 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 .0.** <tr><td>
2d770 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 NULL <td> T
2d780 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 EXT <td> Resu
2d790 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 lt is NULL point
2d7a0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
2d7b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 NULL <td> B
2d7c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 LOB <td> Resu
2d7d0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 lt is NULL point
2d7e0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 er.** <tr><td> I
2d7f0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c NTEGER <td> FL
2d800 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 OAT <td> Conv
2d810 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 ert from integer
2d820 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 to float.** <tr
2d830 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
2d840 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
2d850 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 d> ASCII renderi
2d860 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 ng of the intege
2d870 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
2d880 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c TEGER <td> BL
2d890 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 OB <td> Same
2d8a0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 as INTEGER->TEXT
2d8b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
2d8c0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OAT <td> INTEG
2d8d0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 ER <td> Conver
2d8e0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 t from float to
2d8f0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
2d900 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2d910 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2d920 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
2d930 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a of the float.**
2d940 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2d950 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2d960 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 <td> Same as F
2d970 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 LOAT->TEXT.** <t
2d980 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2d990 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
2d9a0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a td> Use atoi().*
2d9b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2d9c0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
2d9d0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 <td> Use atof
2d9e0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
2d9f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 TEXT <td> B
2da00 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 LOB <td> No c
2da10 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 hange.** <tr><td
2da20 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
2da30 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 INTEGER <td> C
2da40 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 onvert to TEXT t
2da50 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a hen use atoi().*
2da60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2da70 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
2da80 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2da90 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
2daa0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c atof().** <tr><
2dab0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
2dac0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2dad0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d Add a zero term
2dae0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 inator if needed
2daf0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 .** </table>.**
2db00 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
2db10 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 **.** The table
2db20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 above makes refe
2db30 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 rence to standar
2db40 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 d C library func
2db50 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 tions atoi().**
2db60 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c and atof(). SQL
2db70 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 ite does not rea
2db80 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 lly use these fu
2db90 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 nctions. It has
2dba0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 its.** own equi
2dbb0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 valent internal
2dbc0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 routines. The a
2dbd0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 toi() and atof()
2dbe0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 names are.** us
2dbf0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 ed in the table
2dc00 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 for brevity and
2dc10 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 because they are
2dc20 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 familiar to mos
2dc30 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 t.** C programme
2dc40 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 rs..**.** Note t
2dc50 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f hat when type co
2dc60 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c nversions occur,
2dc70 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
2dc80 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 ed by prior.** c
2dc90 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
2dca0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 column_blob(), s
2dcb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2dcc0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 xt(), and/or.**
2dcd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2dce0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 ext16() may be i
2dcf0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 nvalidated..** T
2dd00 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
2dd10 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 and pointer inva
2dd20 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lidations might
2dd30 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 occur.** in the
2dd40 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a following cases:
2dd50 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2dd60 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2dd70 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f content is a BLO
2dd80 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f B and sqlite3_co
2dd90 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a lumn_text() or.*
2dda0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
2ddb0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
2ddc0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 s called. A zer
2ddd0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 o-terminator mig
2dde0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 ht.** need
2ddf0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 to be added to t
2de00 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a he string.</li>.
2de10 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
2de20 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
2de30 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 TF-8 text and sq
2de40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2de50 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 es16() or.**
2de60 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
2de70 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
2de80 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2de90 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2dea0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2deb0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c TF-16.</li>.** <
2dec0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2ded0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 content is UTF-1
2dee0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 6 text and sqlit
2def0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2df00 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
2df10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2df20 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
2df30 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
2df40 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
2df50 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f to UTF-8.</
2df60 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a li>.** </ul>.**.
2df70 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 ** ^Conversions
2df80 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 between UTF-16be
2df90 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 and UTF-16le ar
2dfa0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e e always done in
2dfb0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a place and do.**
2dfc0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 not invalidate
2dfd0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c a prior pointer,
2dfe0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 though of cours
2dff0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 e the content of
2e000 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 the buffer.** t
2e010 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f hat the prior po
2e020 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 inter references
2e030 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 will have been
2e040 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 modified. Other
2e050 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e kinds.** of con
2e060 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 version are done
2e070 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 in place when i
2e080 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 t is possible, b
2e090 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 ut sometimes the
2e0a0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 y.** are not pos
2e0b0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f sible and in tho
2e0c0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 se cases prior p
2e0d0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 ointers are inva
2e0e0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 lidated..**.** T
2e0f0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 he safest and ea
2e100 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 siest to remembe
2e110 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 r policy is to i
2e120 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
2e130 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
2e140 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
2e150 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ways:.**.** <ul>
2e160 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
2e170 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 _column_text() f
2e180 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
2e190 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2e1a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
2e1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2e1c0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ob() followed by
2e1d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2e1e0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
2e1f0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
2e200 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c umn_text16() fol
2e210 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
2e220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2e230 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a )</li>.** </ul>.
2e240 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 **.** In other w
2e250 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 ords, you should
2e260 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f call sqlite3_co
2e270 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 lumn_text(),.**
2e280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2e290 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 lob(), or sqlite
2e2a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2e2b0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 ) first to force
2e2c0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 the result.** i
2e2d0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 nto the desired
2e2e0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 format, then inv
2e2f0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 oke sqlite3_colu
2e300 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
2e310 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2e320 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e bytes16() to fin
2e330 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 d the size of th
2e340 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f e result. Do no
2e350 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 t mix calls.** t
2e360 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2e370 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
2e380 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
2e390 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a with calls to.*
2e3a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
2e3b0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 _bytes16(), and
2e3c0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 do not mix calls
2e3d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2e3e0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 mn_text16().** w
2e3f0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ith calls to sql
2e400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2e410 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 s()..**.** ^The
2e420 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
2e430 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 d are valid unti
2e440 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 l a type convers
2e450 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a ion occurs as.**
2e460 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 described above
2e470 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 , or until [sqli
2e480 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
2e490 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2e4a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2e4b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
2e4c0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d alled. ^The mem
2e4d0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 ory space used t
2e4e0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a o hold strings.*
2e4f0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 * and BLOBs is f
2e500 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c reed automatical
2e510 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f ly. Do <b>not</
2e520 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e b> pass the poin
2e530 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a ters returned.**
2e540 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2e550 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
2e560 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2e570 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 ], etc. into.**
2e580 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
2e590 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d ..**.** ^(If a m
2e5a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
2e5b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
2e5c0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 ring the evaluat
2e5d0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ion of any.** of
2e5e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
2e5f0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 a default value
2e600 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
2e610 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
2e620 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 .** is either th
2e630 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 e integer 0, the
2e640 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
2e650 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 number 0.0, or a
2e660 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
2e670 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 . Subsequent ca
2e680 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
2e690 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 errcode()] will
2e6a0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
2e6b0 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 E_NOMEM].)^.*/.S
2e6c0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2e6d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2e6e0 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 lumn_blob(sqlite
2e6f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2e700 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
2e710 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
2e720 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f n_bytes(sqlite3_
2e730 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2e740 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2e750 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2e760 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f bytes16(sqlite3_
2e770 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2e780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 ;.SQLITE_API dou
2e790 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
2e7a0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
2e7b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2e7c0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
2e7d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
2e7e0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 n_int(sqlite3_st
2e7f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2e800 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
2e810 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
2e820 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 _column_int64(sq
2e830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2e840 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
2e850 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 PI const unsigne
2e860 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f d char *sqlite3_
2e870 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 column_text(sqli
2e880 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
2e890 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
2e8a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
2e8b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2e8c0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2e8d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
2e8e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2e8f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2e900 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2e910 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
2e920 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c _API sqlite3_val
2e930 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ue *sqlite3_colu
2e940 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 mn_value(sqlite3
2e950 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2e960 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2e970 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 EF: Destroy A Pr
2e980 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2e990 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 Object.**.** ^T
2e9a0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
2e9b0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
2e9c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
2e9d0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
2e9e0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 tatement]..** ^I
2e9f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
2ea00 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
2ea10 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e the statement en
2ea20 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 countered no err
2ea30 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 ors.** or if the
2ea40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 statement is ne
2ea50 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 ver been evaluat
2ea60 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ed, then sqlite3
2ea70 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 _finalize() retu
2ea80 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b rns.** SQLITE_OK
2ea90 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 . ^If the most
2eaa0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
2eab0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 n of statement S
2eac0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a failed, then.**
2ead0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2eae0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 e(S) returns the
2eaf0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
2eb00 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ror code] or.**
2eb10 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
2eb20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
2eb30 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
2eb40 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 ze(S) routine ca
2eb50 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
2eb60 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a ny point during.
2eb70 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c ** the life cycl
2eb80 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 e of [prepared s
2eb90 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 tatement] S:.**
2eba0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 before statement
2ebb0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 S is ever evalu
2ebc0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f ated, after.** o
2ebd0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 ne or more calls
2ebe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
2ebf0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 et()], or after
2ec00 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b any call.** to [
2ec10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2ec20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
2ec30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
2ec40 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a statement has.*
2ec50 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 * completed exec
2ec60 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e ution..**.** ^In
2ec70 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 voking sqlite3_f
2ec80 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e inalize() on a N
2ec90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 ULL pointer is a
2eca0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
2ecb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
2ecc0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 cation must fina
2ecd0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 lize every [prep
2ece0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2ecf0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 in order to avoi
2ed00 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 d.** resource le
2ed10 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 aks. It is a gr
2ed20 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 ievous error for
2ed30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
2ed40 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a to try to use.*
2ed50 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 * a prepared sta
2ed60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
2ed70 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
2ed80 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 ed. Any use of
2ed90 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 a prepared.** st
2eda0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 atement after it
2edb0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
2edc0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 zed can result i
2edd0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a n undefined and.
2ede0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 ** undesirable b
2edf0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 ehavior such as
2ee00 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 segfaults and he
2ee10 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a ap corruption..*
2ee20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2ee30 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2ee40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a e(sqlite3_stmt *
2ee50 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2ee60 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
2ee70 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
2ee80 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ent Object.**.**
2ee90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
2eea0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
2eeb0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
2eec0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2eed0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
2eee0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e t back to its in
2eef0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 itial state, rea
2ef00 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 dy to be re-exec
2ef10 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 uted..** ^Any SQ
2ef20 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 L statement vari
2ef30 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 ables that had v
2ef40 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 alues bound to t
2ef50 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 hem using.** the
2ef60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2ef70 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 lob | sqlite3_bi
2ef80 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 nd_*() API] reta
2ef90 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e in their values.
2efa0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 .** Use [sqlite3
2efb0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
2efc0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 )] to reset the
2efd0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 bindings..**.**
2efe0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
2eff0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
2f000 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 e resets the [pr
2f010 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f020 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 ] S.** back to t
2f030 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
2f040 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a its program..**.
2f050 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
2f060 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
2f070 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
2f080 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
2f090 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2f0a0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c S returned [SQL
2f0b0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c ITE_ROW] or [SQL
2f0c0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 ITE_DONE],.** or
2f0d0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 if [sqlite3_ste
2f0e0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 p(S)] has never
2f0f0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c before been call
2f100 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e ed on S,.** then
2f110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2f120 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c S)] returns [SQL
2f130 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e ITE_OK]..**.** ^
2f140 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
2f150 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
2f160 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
2f170 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2f180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
2f190 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f ndicated an erro
2f1a0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 r, then.** [sqli
2f1b0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 te3_reset(S)] re
2f1c0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 turns an appropr
2f1d0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
2f1e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 ]..**.** ^The [s
2f1f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2f200 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 interface does
2f210 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
2f220 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 alues.** of any
2f230 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2f240 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 ob|bindings] on
2f250 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2f260 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 atement] S..*/.S
2f270 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2f280 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 lite3_reset(sqli
2f290 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2f2a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f2b0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 F: Create Or Red
2f2c0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 efine SQL Functi
2f2d0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ons.** KEYWORDS:
2f2e0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 {function creat
2f2f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a ion routines}.**
2f300 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c KEYWORDS: {appl
2f310 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2f320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a SQL function}.**
2f330 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c KEYWORDS: {appl
2f340 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2f350 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a SQL functions}.*
2f360 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 *.** ^These func
2f370 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 tions (collectiv
2f380 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 ely known as "fu
2f390 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
2f3a0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 routines").** ar
2f3b0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 e used to add SQ
2f3c0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
2f3d0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 ggregates or to
2f3e0 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 redefine the beh
2f3f0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 avior.** of exis
2f400 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f ting SQL functio
2f410 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
2f420 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 . The only diff
2f430 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a erences between.
2f440 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 ** these routine
2f450 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 s are the text e
2f460 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 ncoding expected
2f470 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f for.** the seco
2f480 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 nd parameter (th
2f490 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 e name of the fu
2f4a0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 nction being cre
2f4b0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ated).** and the
2f4c0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 presence or abs
2f4d0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 ence of a destru
2f4e0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f ctor callback fo
2f4f0 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 r.** the applica
2f500 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
2f510 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 r..**.** ^The fi
2f520 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
2f530 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2f540 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 onnection] to wh
2f550 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 ich the SQL.** f
2f560 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 unction is to be
2f570 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 added. ^If an
2f580 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 application uses
2f590 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 more than one d
2f5a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
2f5b0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 ction then appli
2f5c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2f5d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 QL functions mus
2f5e0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f t be added.** to
2f5f0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
2f600 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 onnection separa
2f610 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tely..**.** ^The
2f620 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
2f630 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
2f640 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2f650 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 n to be created
2f660 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e or.** redefined.
2f670 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 ^The length of
2f680 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d the name is lim
2f690 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 ited to 255 byte
2f6a0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 s in a UTF-8.**
2f6b0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 representation,
2f6c0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 exclusive of the
2f6d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 zero-terminator
2f6e0 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 . ^Note that th
2f6f0 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 e name.** length
2f700 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 limit is in UTF
2f710 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 -8 bytes, not ch
2f720 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 aracters nor UTF
2f730 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 -16 bytes. .**
2f740 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 ^Any attempt to
2f750 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f create a functio
2f760 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 n with a longer
2f770 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 name.** will res
2f780 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d ult in [SQLITE_M
2f790 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 ISUSE] being ret
2f7a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
2f7b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2f7c0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 r (nArg).** is t
2f7d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
2f7e0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 uments that the
2f7f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
2f800 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b ** aggregate tak
2f810 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 es. ^If this par
2f820 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 ameter is -1, th
2f830 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 en the SQL funct
2f840 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
2f850 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 ate may take any
2f860 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
2f870 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 ents between 0 a
2f880 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 nd the limit.**
2f890 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f set by [sqlite3_
2f8a0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c limit]([SQLITE_L
2f8b0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
2f8c0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 G]). If the thi
2f8d0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 rd.** parameter
2f8e0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 is less than -1
2f8f0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 or greater than
2f900 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 127 then the beh
2f910 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 avior is.** unde
2f920 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2f930 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2f940 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 er, eTextRep, sp
2f950 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 ecifies what.**
2f960 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 [SQLITE_UTF8 | t
2f970 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 ext encoding] th
2f980 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 is SQL function
2f990 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 prefers for.** i
2f9a0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ts parameters.
2f9b0 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 Every SQL functi
2f9c0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
2f9d0 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 n must be able t
2f9e0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 o work.** with U
2f9f0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 TF-8, UTF-16le,
2fa00 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 or UTF-16be. Bu
2fa10 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 t some implement
2fa20 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a ations may be.**
2fa30 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 more efficient
2fa40 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e with one encodin
2fa50 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 g than another.
2fa60 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e ^An application
2fa70 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 may.** invoke s
2fa80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2fa90 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 nction() or sqli
2faa0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2fab0 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 ion16() multiple
2fac0 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 .** times with t
2fad0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
2fae0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 but with differ
2faf0 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 ent values of eT
2fb00 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e extRep..** ^When
2fb10 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
2fb20 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
2fb30 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 same function a
2fb40 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 re available, SQ
2fb50 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 Lite.** will pic
2fb60 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 k the one that i
2fb70 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 nvolves the leas
2fb80 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 t amount of data
2fb90 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 conversion..**
2fba0 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 If there is only
2fbb0 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d a single implem
2fbc0 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 entation which d
2fbd0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 oes not care wha
2fbe0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 t text.** encodi
2fbf0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e ng is used, then
2fc00 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
2fc10 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b ment should be [
2fc20 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a SQLITE_ANY]..**.
2fc30 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 ** ^(The fifth p
2fc40 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 arameter is an a
2fc50 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 rbitrary pointer
2fc60 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 . The implement
2fc70 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 ation of the.**
2fc80 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 function can gai
2fc90 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 n access to this
2fca0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b pointer using [
2fcb0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
2fcc0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 a()].)^.**.** ^T
2fcd0 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 he sixth, sevent
2fce0 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 h and eighth par
2fcf0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 ameters, xFunc,
2fd00 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
2fd10 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 , are.** pointer
2fd20 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 s to C-language
2fd30 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 functions that i
2fd40 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
2fd50 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
2fd60 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 aggregate. ^A sc
2fd70 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f alar SQL functio
2fd80 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
2fd90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2fda0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c the xFunc.** cal
2fdb0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c lback only; NULL
2fdc0 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 pointers must b
2fdd0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
2fde0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
2fdf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
2fe00 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 ^An aggregate SQ
2fe10 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
2fe20 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
2fe30 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a ation of xStep.*
2fe40 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 * and xFinal and
2fe50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 NULL pointer mu
2fe60 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 st be passed for
2fe70 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 xFunc. ^To dele
2fe80 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a te an existing.*
2fe90 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f * SQL function o
2fea0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 r aggregate, pas
2feb0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 s NULL pointers
2fec0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 for all three fu
2fed0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 nction.** callba
2fee0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 cks..**.** ^(If
2fef0 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 the ninth parame
2ff00 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ter to sqlite3_c
2ff10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
2ff20 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 2() is not NULL,
2ff30 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 .** then it is d
2ff40 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 estructor for th
2ff50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
2ff60 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 ta pointer. .**
2ff70 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
2ff80 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 s invoked when t
2ff90 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 he function is d
2ffa0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 eleted, either b
2ffb0 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c y being.** overl
2ffc0 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 oaded or when th
2ffd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2ffe0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a ction closes.)^.
2fff0 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 ** ^The destruct
30000 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b or is also invok
30010 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 ed if the call t
30020 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 o.** sqlite3_cre
30030 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
30040 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 ) fails..** ^Whe
30050 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 n the destructor
30060 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 callback of the
30070 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 tenth parameter
30080 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a is invoked, it.
30090 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 ** is passed a s
300a0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
300b0 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f hich is a copy o
300c0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
300d0 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 n data .** point
300e0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 er which was the
300f0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
30100 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 to sqlite3_crea
30110 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 te_function_v2()
30120 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 ..**.** ^It is p
30130 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 ermitted to regi
30140 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d ster multiple im
30150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
30160 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e the same.** fun
30170 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 ctions with the
30180 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 same name but wi
30190 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 th either differ
301a0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a ing numbers of.*
301b0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 * arguments or d
301c0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 iffering preferr
301d0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
301e0 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c s. ^SQLite will
301f0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c use.** the impl
30200 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 ementation that
30210 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 most closely mat
30220 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 ches the way in
30230 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c which the.** SQL
30240 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
30250 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 d. ^A function
30260 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
30270 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 ith a non-negati
30280 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d ve.** nArg param
30290 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 eter is a better
302a0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
302b0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
302c0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 ation with.** a
302d0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 negative nArg.
302e0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 ^A function wher
302f0 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
30300 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a text encoding.**
30310 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 matches the dat
30320 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 abase encoding i
30330 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 s a better.** ma
30340 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
30350 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
30360 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 coding is differ
30370 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e ent. .** ^A fun
30380 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
30390 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 encoding differe
303a0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 nce is between U
303b0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 TF16le and UTF16
303c0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 be.** is a close
303d0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
303e0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
303f0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
30400 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 rence is.** betw
30410 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 een UTF8 and UTF
30420 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 16..**.** ^Built
30430 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 -in functions ma
30440 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 y be overloaded
30450 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 by new applicati
30460 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
30470 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 ions..**.** ^An
30480 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
30490 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
304a0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c permitted to cal
304b0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 l other.** SQLit
304c0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 e interfaces. H
304d0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c owever, such cal
304e0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 ls must not.** c
304f0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
30500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 e connection nor
30510 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 finalize or res
30520 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a et the prepared.
30530 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 ** statement in
30540 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 which the functi
30550 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
30560 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
30570 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
30580 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 function(. sqli
30590 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
305a0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
305b0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
305c0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
305d0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
305e0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
305f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
30600 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
30610 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
30620 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
30630 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
30640 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
30650 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
30660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
30670 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
30680 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
30690 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 e_function16(.
306a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
306b0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 onst void *zFunc
306c0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
306d0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
306e0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
306f0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
30700 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
30710 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
30720 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
30730 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
30740 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
30750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
30760 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
30770 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
30780 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 xt*).);.SQLITE_A
30790 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
307a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
307b0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
307c0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
307d0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
307e0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
307f0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
30800 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
30810 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
30820 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
30830 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
30840 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
30850 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
30860 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
30870 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
30880 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
30890 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 context*),. voi
308a0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
308b0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*).);../*.** CA
308c0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 PI3REF: Text Enc
308d0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 odings.**.** The
308e0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 se constant defi
308f0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ne integer codes
30900 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 that represent
30910 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 the various.** t
30920 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 ext encodings su
30930 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
30940 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
30950 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 LITE_UTF8
30960 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
30970 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 LITE_UTF16LE
30980 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
30990 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 LITE_UTF16BE
309a0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
309b0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 LITE_UTF16
309c0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 4 /* Use
309d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
309e0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
309f0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 ITE_ANY
30a00 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
30a10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
30a20 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 on only */.#defi
30a30 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f ne SQLITE_UTF16_
30a40 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a ALIGNED 8 /*
30a50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
30a60 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a collation only *
30a70 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
30a80 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 F: Deprecated Fu
30a90 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 nctions.** DEPRE
30aa0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 CATED.**.** Thes
30ab0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
30ac0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 [deprecated]. I
30ad0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 n order to maint
30ae0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ain.** backwards
30af0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 compatibility w
30b00 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 ith older code,
30b10 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
30b20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 continue .** to
30b30 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 be supported. H
30b40 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c owever, new appl
30b50 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
30b60 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 avoid.** the use
30b70 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
30b80 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e ons. To help en
30b90 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 courage people t
30ba0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 o avoid.** using
30bb0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
30bc0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 , we are not goi
30bd0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 ng to tell you w
30be0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a hat they do..*/.
30bf0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f #ifndef SQLITE_O
30c00 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 MIT_DEPRECATED.S
30c10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
30c20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
30c30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
30c40 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f e_count(sqlite3_
30c50 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
30c60 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
30c70 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
30c80 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
30c90 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
30ca0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
30cb0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
30cc0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 ite3_transfer_bi
30cd0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 ndings(sqlite3_s
30ce0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 tmt*, sqlite3_st
30cf0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 mt*);.SQLITE_API
30d00 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
30d10 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 ED int sqlite3_g
30d20 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f lobal_recover(vo
30d30 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
30d40 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
30d50 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 D void sqlite3_t
30d60 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f hread_cleanup(vo
30d70 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
30d80 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
30d90 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 D int sqlite3_me
30da0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 mory_alarm(void(
30db0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
30dc0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 _int64,int),.
30dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30de0 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 void*,sqlite3
30df0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a _int64);.#endif.
30e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30e10 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 Obtaining SQL F
30e20 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 unction Paramete
30e30 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 r Values.**.** T
30e40 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d he C-language im
30e50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
30e60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
30e70 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 d aggregates use
30e80 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 s.** this set of
30e90 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 interface routi
30ea0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 nes to access th
30eb0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 e parameter valu
30ec0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e es on.** the fun
30ed0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
30ee0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 te..**.** The xF
30ef0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 unc (for scalar
30f00 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 functions) or xS
30f10 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 tep (for aggrega
30f20 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a tes) parameters.
30f30 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
30f40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
30f50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
30f60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
30f70 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 ()].** define ca
30f80 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 llbacks that imp
30f90 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
30fa0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
30fb0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 regates..** The
30fc0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
30fd0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 these callbacks
30fe0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
30ff0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b pointers to.** [
31000 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
31010 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
31020 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 . There is one
31030 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
31040 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 object for.** ea
31050 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ch parameter to
31060 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
31070 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
31080 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a s are used to.**
31090 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 extract values
310a0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 from the [sqlite
310b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
310c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
310d0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 utines work only
310e0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 with [protected
310f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
31100 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 objects..** Any
31110 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
31120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
31130 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
31140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a sqlite3_value].
31150 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 ** object result
31160 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 s in undefined b
31170 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e ehavior..**.** ^
31180 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
31190 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 ork just like th
311a0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
311b0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
311c0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 unctions].** exc
311d0 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 ept that these
311e0 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 routines take a
311f0 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 single [protecte
31200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
31210 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 object.** point
31220 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 er instead of a
31230 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 [sqlite3_stmt*]
31240 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 pointer and an i
31250 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 nteger column nu
31260 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 mber..**.** ^The
31270 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
31280 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 ext16() interfac
31290 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 e extracts a UTF
312a0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e -16 string.** in
312b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
312c0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f -order of the ho
312d0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 st machine. ^Th
312e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c e.** sqlite3_val
312f0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e ue_text16be() an
31300 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f d sqlite3_value_
31310 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 text16le() inter
31320 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 faces.** extract
31330 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 UTF-16 strings
31340 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e as big-endian an
31350 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 d little-endian
31360 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
31370 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
31380 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
31390 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 type() interface
313a0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 attempts to app
313b0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 ly.** numeric af
313c0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 finity to the va
313d0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 lue. This means
313e0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 that an attempt
313f0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 is.** made to c
31400 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 onvert the value
31410 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f to an integer o
31420 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 r floating point
31430 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 . If.** such a
31440 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f conversion is po
31450 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c ssible without l
31460 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 oss of informati
31470 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 on (in other.**
31480 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 words, if the va
31490 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 lue is a string
314a0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 that looks like
314b0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 a number).** the
314c0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e n the conversion
314d0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 is performed.
314e0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e Otherwise no con
314f0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a version occurs..
31500 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 ** The [SQLITE_I
31510 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 NTEGER | datatyp
31520 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 e] after convers
31530 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e ion is returned.
31540 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 )^.**.** Please
31550 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 pay particular a
31560 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 ttention to the
31570 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f fact that the po
31580 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a inter returned.*
31590 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
315a0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b value_blob()], [
315b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
315c0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 xt()], or.** [sq
315d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
315e0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 16()] can be inv
315f0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 alidated by a su
31600 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
31610 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
31620 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 ue_bytes()], [sq
31630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
31640 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 s16()], [sqlite3
31650 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a _value_text()],.
31660 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 ** or [sqlite3_v
31670 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a alue_text16()]..
31680 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
31690 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
316a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
316b0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 e thread as.** t
316c0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
316d0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 that supplied th
316e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
316f0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a *] parameters..*
31700 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
31710 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
31720 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 _value_blob(sqli
31730 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
31740 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
31750 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
31760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
31770 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
31780 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
31790 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 tes16(sqlite3_va
317a0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
317b0 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 I double sqlite3
317c0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 _value_double(sq
317d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
317e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
317f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
31800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
31810 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
31820 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
31830 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 3_value_int64(sq
31840 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
31850 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
31860 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
31870 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
31880 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
31890 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
318a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
318b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 3_value_text16(s
318c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
318d0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
318e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
318f0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 alue_text16le(sq
31900 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
31910 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
31920 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
31930 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c lue_text16be(sql
31940 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
31950 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
31960 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
31970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
31980 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
31990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 sqlite3_value_nu
319a0 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 meric_type(sqlit
319b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a e3_value*);../*.
319c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
319d0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 ain Aggregate Fu
319e0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a nction Context.*
319f0 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 *.** Implementat
31a00 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 ions of aggregat
31a10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
31a20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 use this.** rout
31a30 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ine to allocate
31a40 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 memory for stori
31a50 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a ng their state..
31a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
31a70 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 time the sqlite
31a80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
31a90 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 ext(C,N) routine
31aa0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 is called .** f
31ab0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
31ac0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
31ad0 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c on, SQLite.** al
31ae0 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d locates N of mem
31af0 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 ory, zeroes out
31b00 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 that memory, and
31b10 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
31b20 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 er.** to the new
31b30 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 memory. ^On sec
31b40 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
31b50 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 nt calls to.** s
31b60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
31b70 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 _context() for t
31b80 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 he same aggregat
31b90 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 e function insta
31ba0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 nce,.** the same
31bb0 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 buffer is retur
31bc0 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 ned. Sqlite3_ag
31bd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
31be0 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a ) is normally.**
31bf0 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 called once for
31c00 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e each invocation
31c10 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 of the xStep ca
31c20 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 llback and then
31c30 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 one.** last time
31c40 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c when the xFinal
31c50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
31c60 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f oked. ^(When no
31c70 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 rows match.** a
31c80 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 n aggregate quer
31c90 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 y, the xStep() c
31ca0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 allback of the a
31cb0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
31cc0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
31cd0 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c ion is never cal
31ce0 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 led and xFinal()
31cf0 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 is called exact
31d00 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 ly once..** In t
31d10 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 hose cases, sqli
31d20 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
31d30 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 ntext() might be
31d40 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a called for the.
31d50 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 ** first time fr
31d60 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c om within xFinal
31d70 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ().)^.**.** ^The
31d80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
31d90 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
31da0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
31db0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a a NULL pointer .
31dc0 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 ** when first ca
31dd0 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 lled if N is les
31de0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
31df0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 to zero or if a
31e00 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
31e10 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e te error occurs.
31e20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f .**.** ^(The amo
31e30 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c unt of space all
31e40 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 ocated by sqlite
31e50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
31e60 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 ext(C,N) is.** d
31e70 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 etermined by the
31e80 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 N parameter on
31e90 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c first successful
31ea0 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 call. Changing
31eb0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 the.** value of
31ec0 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 N in subsequent
31ed0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
31ee0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
31ef0 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 xt() within.** t
31f00 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 he same aggregat
31f10 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 e function insta
31f20 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 nce will not res
31f30 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a ize the memory.*
31f40 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 * allocation.)^
31f50 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e Within the xFin
31f60 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 al callback, it
31f70 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 is customary to
31f80 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 set.** N=0 in ca
31f90 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 lls to sqlite3_a
31fa0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
31fb0 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f (C,N) so that no
31fc0 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d .** pointless m
31fd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
31fe0 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e s occur..**.** ^
31ff0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 SQLite automatic
32000 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d ally frees the m
32010 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 emory allocated
32020 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 by .** sqlite3_a
32030 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
32040 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 () when the aggr
32050 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 egate query conc
32060 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ludes..**.** The
32070 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
32080 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 must be a copy
32090 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
320a0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c e3_context | SQL
320b0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 function contex
320c0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 t] that is the f
320d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a irst parameter.*
320e0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f * to the xStep o
320f0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 r xFinal callbac
32100 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 k routine that i
32110 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 mplements the ag
32120 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 gregate.** funct
32130 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
32140 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
32150 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
32160 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
32170 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 hich.** the aggr
32180 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
32190 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
321a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
321b0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 d *sqlite3_aggre
321c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c gate_context(sql
321d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
321e0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a nt nBytes);../*.
321f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 ** CAPI3REF: Use
32200 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 r Data For Funct
32210 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ions.**.** ^The
32220 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
32230 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
32240 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
32250 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
32260 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 hat was the pUse
32270 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 rData parameter
32280 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 (the 5th paramet
32290 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
322a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
322b0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
322c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
322d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
322e0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
322f0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
32300 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
32310 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
32320 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
32330 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
32340 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
32350 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
32360 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
32370 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
32380 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
32390 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 unning..*/.SQLIT
323a0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
323b0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 te3_user_data(sq
323c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
323d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
323e0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
323f0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 ction For Functi
32400 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ons.**.** ^The s
32410 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
32420 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 b_handle() inter
32430 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
32440 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f opy of.** the po
32450 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 inter to the [da
32460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
32470 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 n] (the 1st para
32480 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 meter).** of the
32490 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
324a0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 _function()].**
324b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
324c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
324d0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 ] routines that
324e0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 originally.** re
324f0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 gistered the app
32500 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
32510 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 function..*/.SQ
32520 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
32530 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 *sqlite3_contex
32540 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 t_db_handle(sqli
32550 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
32560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32570 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 Function Auxilia
32580 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 ry Data.**.** Th
32590 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 e following two
325a0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
325b0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 used by scalar
325c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f SQL functions to
325d0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 .** associate me
325e0 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 tadata with argu
325f0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 ment values. If
32600 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 the same value i
32610 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d s passed to.** m
32620 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 ultiple invocati
32630 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
32640 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 SQL function dur
32650 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 ing query execut
32660 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f ion, under.** so
32670 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 me circumstances
32680 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 the associated
32690 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 metadata may be
326a0 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 preserved. This
326b0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 may.** be used,
326c0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 for example, to
326d0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 add a regular-ex
326e0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e pression matchin
326f0 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 g scalar.** func
32700 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c tion. The compil
32710 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ed version of th
32720 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
32730 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 sion is stored a
32740 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 s.** metadata as
32750 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
32760 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 e SQL value pass
32770 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 ed as the regula
32780 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 r expression.**
32790 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f pattern. The co
327a0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 mpiled regular e
327b0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 xpression can be
327c0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 reused on multi
327d0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ple.** invocatio
327e0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
327f0 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 unction so that
32800 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 the original pat
32810 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 tern string.** d
32820 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
32830 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e be recompiled on
32840 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e each invocation
32850 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
32860 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
32870 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
32880 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
32890 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a o the metadata.*
328a0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 * associated by
328b0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
328c0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 auxdata() functi
328d0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 on with the Nth
328e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 argument.** valu
328f0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 e to the applica
32900 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
32910 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 ction. ^If no me
32920 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 tadata has been
32930 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 ever.** been set
32940 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 for the Nth arg
32950 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e ument of the fun
32960 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 ction, or if the
32970 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
32980 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d * function param
32990 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 eter has changed
329a0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d since the meta-
329b0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a data was set,.**
329c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 then sqlite3_ge
329d0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 t_auxdata() retu
329e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
329f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
32a00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
32a10 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ta() interface s
32a20 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 aves the metadat
32a30 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 a.** pointed to
32a40 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d by its 3rd param
32a50 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 eter as the meta
32a60 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 data for the N-t
32a70 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 h.** argument of
32a80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
32a90 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
32aa0 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a n. Subsequent.*
32ab0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
32ac0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
32ad0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 might return th
32ae0 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 is data, if it h
32af0 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 as.** not been d
32b00 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 estroyed..** ^If
32b10 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c it is not NULL,
32b20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
32b30 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
32b40 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 or.** function g
32b50 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 iven by the 4th
32b60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
32b70 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
32b80 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 () on.** the met
32b90 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 adata when the c
32ba0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
32bb0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
32bc0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 changes.** or wh
32bd0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
32be0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 ment completes,
32bf0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
32c00 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c first..**.** SQL
32c10 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 ite is free to c
32c20 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 all the destruct
32c30 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 or and drop meta
32c40 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 data on any.** p
32c50 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
32c60 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
32c70 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 time. ^The only
32c80 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 guarantee is th
32c90 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 at.** the destru
32ca0 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c ctor will be cal
32cb0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d led before the m
32cc0 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 etadata is dropp
32cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 ed..**.** ^(In p
32ce0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 ractice, metadat
32cf0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 a is preserved b
32d00 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 etween function
32d10 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 calls for.** exp
32d20 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 ressions that ar
32d30 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f e constant at co
32d40 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 mpile time. This
32d50 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 includes litera
32d60 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 l.** values and
32d70 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a [parameters].)^.
32d80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
32d90 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
32da0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
32db0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
32dc0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e h.** the SQL fun
32dd0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
32de0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
32df0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 void *sqlite3_ge
32e00 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
32e10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
32e20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 N);.SQLITE_API v
32e30 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f oid sqlite3_set_
32e40 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
32e50 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c context*, int N,
32e60 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 void*, void (*)
32e70 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a (void*));.../*.*
32e80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 * CAPI3REF: Cons
32e90 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 tants Defining S
32ea0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f pecial Destructo
32eb0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a r Behavior.**.**
32ec0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 These are speci
32ed0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 al values for th
32ee0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 e destructor tha
32ef0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 t is passed in a
32f00 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 s the.** final a
32f10 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 rgument to routi
32f20 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
32f30 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 3_result_blob()]
32f40 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 . ^If the destr
32f50 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e uctor.** argumen
32f60 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 t is SQLITE_STAT
32f70 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 IC, it means tha
32f80 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f t the content po
32f90 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e inter is constan
32fa0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 t.** and will ne
32fb0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 ver change. It
32fc0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
32fd0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 be destroyed.
32fe0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 ^The.** SQLITE_T
32ff0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d RANSIENT value m
33000 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
33010 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c ntent will likel
33020 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 y change in.** t
33030 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 he near future a
33040 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 nd that SQLite s
33050 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f hould make its o
33060 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
33070 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e of.** the conten
33080 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 t before returni
33090 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 ng..**.** The ty
330a0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 pedef is necessa
330b0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e ry to work aroun
330c0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 d problems in ce
330d0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d rtain.** C++ com
330e0 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 pilers..*/.typed
330f0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
33100 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
33110 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 e)(void*);.#defi
33120 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 ne SQLITE_STATIC
33130 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f ((sqlite3_
33140 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
33150 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0).#define SQLIT
33160 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 E_TRANSIENT ((
33170 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
33180 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a or_type)-1)../*.
33190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
331a0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 ting The Result
331b0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 Of An SQL Functi
331c0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 on.**.** These r
331d0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
331e0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 by the xFunc or
331f0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
33200 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d s that.** implem
33210 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ent SQL function
33220 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
33230 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 . See.** [sqlit
33240 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
33250 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
33260 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
33270 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 on16()].** for a
33280 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
33290 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
332a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 se functions wor
332b0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 k very much like
332c0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 the [parameter
332d0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 binding] family
332e0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 of.** functions
332f0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c used to bind val
33300 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 ues to host para
33310 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 meters in prepar
33320 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a ed statements..*
33330 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b * Refer to the [
33340 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 SQL parameter] d
33350 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
33360 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
33370 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e rmation..**.** ^
33380 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
33390 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 lt_blob() interf
333a0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
333b0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 ult from.** an a
333c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
333d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
333e0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 e the BLOB whose
333f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e content is poin
33400 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 ted.** to by the
33410 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
33420 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e r and which is N
33430 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 bytes long wher
33440 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 e N is the.** th
33450 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ird parameter..*
33460 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
33470 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 3_result_zeroblo
33480 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 b() interfaces s
33490 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 et the result of
334a0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
334b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
334c0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f tion to be a BLO
334d0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c B containing all
334e0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 zero.** bytes a
334f0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 nd N bytes in si
33500 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 ze, where N is t
33510 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
33520 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2nd parameter..*
33530 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
33540 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
33550 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
33560 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
33570 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
33580 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33590 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 ion to be a floa
335a0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
335b0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
335c0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
335d0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 t..**.** ^The sq
335e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
335f0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
33600 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
33610 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 ) functions.** c
33620 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ause the impleme
33630 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f nted SQL functio
33640 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 n to throw an ex
33650 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c ception..** ^SQL
33660 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 ite uses the str
33670 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ing pointed to b
33680 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 y the.** 2nd par
33690 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
336a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
336b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
336c0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
336d0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 as the text of a
336e0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
336f0 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 ^SQLite interp
33700 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a rets the error.*
33710 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 * message string
33720 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 from sqlite3_re
33730 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 sult_error() as
33740 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a UTF-8. ^SQLite.*
33750 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 * interprets the
33760 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
33770 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33780 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 r16() as UTF-16
33790 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 in native.** byt
337a0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 e order. ^If th
337b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
337c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
337d0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
337e0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
337f0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
33800 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
33810 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
33820 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
33830 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
33840 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
33850 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
33860 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 * ^If the third
33870 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
33880 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33890 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 r() or.** sqlite
338a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
338b0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 () is non-negati
338c0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
338d0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a akes that many.*
338e0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 * bytes (not cha
338f0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 racters) from th
33900 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
33910 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 as the error mes
33920 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 sage..** ^The sq
33930 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33940 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
33950 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
33960 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 ).** routines ma
33970 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 ke a private cop
33980 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d y of the error m
33990 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f essage text befo
339a0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 re.** they retur
339b0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 n. Hence, the c
339c0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
339d0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f can deallocate o
339e0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 r.** modify the
339f0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 text after they
33a00 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 return without h
33a10 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c arm..** ^The sql
33a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33a30 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f r_code() functio
33a40 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 n changes the er
33a50 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 ror code.** retu
33a60 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 rned by SQLite a
33a70 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e s a result of an
33a80 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 error in a func
33a90 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 tion. ^By defau
33aa0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 lt,.** the error
33ab0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f code is SQLITE_
33ac0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 ERROR. ^A subse
33ad0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
33ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33af0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 or().** or sqlit
33b00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
33b10 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 6() resets the e
33b20 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c rror code to SQL
33b30 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a ITE_ERROR..**.**
33b40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
33b50 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 sult_error_toobi
33b60 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 g() interface ca
33b70 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
33b80 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 hrow an.** error
33b90 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
33ba0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f a string or BLO
33bb0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f B is too long to
33bc0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a represent..**.*
33bd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
33be0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
33bf0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 m() interface ca
33c00 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
33c10 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 hrow an.** error
33c20 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
33c30 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
33c40 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a tion failed..**.
33c50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
33c60 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 result_int() int
33c70 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
33c80 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
33c90 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
33ca0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33cb0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 ion to be the 32
33cc0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
33cd0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
33ce0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
33cf0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
33d00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
33d10 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 nt64() interface
33d20 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
33d30 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
33d40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
33d50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
33d60 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 be the 64-bit s
33d70 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
33d80 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
33d90 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
33da0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33db0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
33dc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
33dd0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
33de0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
33df0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
33e00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
33e10 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
33e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33e30 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f text(), sqlite3_
33e40 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c result_text16(),
33e50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
33e60 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 lt_text16le(), a
33e70 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
33e80 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 t_text16be() int
33e90 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 erfaces.** set t
33ea0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
33eb0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
33ec0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33ed0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 ion to be.** a t
33ee0 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 ext string which
33ef0 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 is represented
33f00 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 as UTF-8, UTF-16
33f10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
33f20 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 er,.** UTF-16 li
33f30 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 ttle endian, or
33f40 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 UTF-16 big endia
33f50 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
33f60 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 .** ^SQLite take
33f70 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c s the text resul
33f80 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 t from the appli
33f90 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 cation from.** t
33fa0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
33fb0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
33fc0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
33fd0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 erfaces..** ^If
33fe0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
33ff0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
34000 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
34010 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e terfaces.** is n
34020 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 egative, then SQ
34030 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c Lite takes resul
34040 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 t text from the
34050 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 2nd parameter.**
34060 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
34070 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
34080 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 r..** ^If the 3r
34090 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
340a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
340b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
340c0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 es.** is non-neg
340d0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d ative, then as m
340e0 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 any bytes (not c
340f0 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 haracters) of th
34100 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 e text.** pointe
34110 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 d to by the 2nd
34120 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 parameter are ta
34130 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 ken as the appli
34140 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a cation-defined.*
34150 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c * function resul
34160 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 t. If the 3rd p
34170 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d arameter is non-
34180 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 negative, then i
34190 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 t.** must be the
341a0 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 byte offset int
341b0 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 o the string whe
341c0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 re the NUL termi
341d0 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 nator would.** a
341e0 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 ppear if the str
341f0 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 ing where NUL te
34200 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
34210 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
34220 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 occur.** in the
34230 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 string at a byt
34240 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 e offset that is
34250 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 less than the v
34260 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a alue of the 3rd.
34270 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 ** parameter, th
34280 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 en the resulting
34290 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e string will con
342a0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 tain embedded NU
342b0 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 Ls and the.** re
342c0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 sult of expressi
342d0 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e ons operating on
342e0 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d strings with em
342f0 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 bedded NULs is u
34300 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 ndefined..** ^If
34310 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
34320 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
34330 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
34340 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 nterfaces.** or
34350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
34360 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c lob is a non-NUL
34370 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
34380 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 SQLite calls tha
34390 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 t.** function as
343a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
343b0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 on the text or B
343c0 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 LOB result when
343d0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 it has.** finish
343e0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 ed using that re
343f0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 sult..** ^If the
34400 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
34410 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
34420 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
34430 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 faces or to.** s
34440 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
34450 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
34460 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
34470 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 E_STATIC, then S
34480 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 QLite.** assumes
34490 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f that the text o
344a0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 r BLOB result is
344b0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 in constant spa
344c0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a ce and does not.
344d0 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 ** copy the cont
344e0 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d ent of the param
344f0 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 eter nor call a
34500 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 destructor on th
34510 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 e content.** whe
34520 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
34530 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
34540 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ult..** ^If the
34550 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
34560 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
34570 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
34580 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
34590 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
345a0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f s the special co
345b0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 nstant SQLITE_TR
345c0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 ANSIENT.** then
345d0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
345e0 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c opy of the resul
345f0 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 t into space obt
34600 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 ained from.** fr
34610 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
34620 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 oc()] before it
34630 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
34640 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
34650 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
34660 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
34670 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
34680 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34690 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
346a0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 e a copy the.**
346b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
346c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
346d0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ct specified by
346e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
346f0 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 r. ^The.** sqli
34700 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
34710 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b () interface mak
34720 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
34730 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
34740 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 .** so that the
34750 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
34760 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 specified in the
34770 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 parameter may c
34780 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 hange or.** be d
34790 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 eallocated after
347a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
347b0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 value() returns
347c0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a without harm..**
347d0 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ^A [protected s
347e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
347f0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 ject may always
34800 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e be used where an
34810 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
34820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
34830 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 object is requir
34840 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a ed, so either.**
34850 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 kind of [sqlite
34860 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
34870 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 can be used with
34880 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
34890 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 .**.** If these
348a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
348b0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 led from within
348c0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 the different th
348d0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 read.** than the
348e0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 one containing
348f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34900 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34910 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a that received.*
34920 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * the [sqlite3_c
34930 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c ontext] pointer,
34940 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
34950 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 undefined..*/.S
34960 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
34970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
34980 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
34990 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
349a0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
349b0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
349c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
349d0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
349e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
349f0 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f double);.SQLITE_
34a00 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
34a10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 _result_error(sq
34a20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
34a30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
34a40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
34a50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
34a60 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 t_error16(sqlite
34a70 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
34a80 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 t void*, int);.S
34a90 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
34aa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
34ab0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 ror_toobig(sqlit
34ac0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
34ad0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
34ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
34af0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 or_nomem(sqlite3
34b00 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
34b10 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
34b20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
34b30 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f _code(sqlite3_co
34b40 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 ntext*, int);.SQ
34b50 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
34b60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
34b70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
34b80 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
34b90 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
34ba0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
34bb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
34bc0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
34bd0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
34be0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
34bf0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ull(sqlite3_cont
34c00 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
34c10 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
34c20 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 esult_text(sqlit
34c30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
34c40 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 st char*, int, v
34c50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
34c60 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
34c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
34c80 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ext16(sqlite3_co
34c90 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
34ca0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
34cb0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
34cc0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
34cd0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
34ce0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
34cf0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
34d00 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
34d10 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
34d20 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
34d30 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 esult_text16be(s
34d40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
34d50 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
34d60 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
34d70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
34d80 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
34d90 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f t_value(sqlite3_
34da0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
34db0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
34dc0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
34dd0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
34de0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
34df0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a xt*, int n);../*
34e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
34e10 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 fine New Collati
34e20 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a ng Sequences.**.
34e30 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 ** ^These functi
34e40 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c ons add, remove,
34e50 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f or modify a [co
34e60 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 llation] associa
34e70 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ted.** with the
34e80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
34e90 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
34ea0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
34eb0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
34ec0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f e name of the co
34ed0 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 llation is a UTF
34ee0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 -8 string.** for
34ef0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
34f00 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 collation() and
34f10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
34f20 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a ollation_v2().**
34f30 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 and a UTF-16 st
34f40 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
34f50 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 yte order for sq
34f60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
34f70 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e lation16()..** ^
34f80 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 Collation names
34f90 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 that compare equ
34fa0 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 al according to
34fb0 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d [sqlite3_strnicm
34fc0 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 p()] are.** cons
34fd0 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 idered to be the
34fe0 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a same name..**.*
34ff0 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 * ^(The third ar
35000 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 gument (eTextRep
35010 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 ) must be one of
35020 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a the constants:.
35030 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
35040 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a [SQLITE_UTF8],.*
35050 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 * <li> [SQLITE_U
35060 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e TF16LE],.** <li>
35070 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
35080 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
35090 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a TE_UTF16], or.**
350a0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
350b0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a F16_ALIGNED]..**
350c0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 </ul>)^.** ^The
350d0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 eTextRep argume
350e0 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 nt determines th
350f0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 e encoding of st
35100 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 rings passed.**
35110 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 to the collating
35120 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 function callba
35130 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a ck, xCallback..*
35140 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 * ^The [SQLITE_U
35150 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 TF16] and [SQLIT
35160 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
35170 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 values for eTex
35180 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 tRep.** force st
35190 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 rings to be UTF1
351a0 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 6 with native by
351b0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 te order..** ^Th
351c0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f e [SQLITE_UTF16_
351d0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 ALIGNED] value f
351e0 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 or eTextRep forc
351f0 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 es strings to be
35200 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 gin.** on an eve
35210 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a n byte address..
35220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
35230 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 h argument, pArg
35240 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 , is an applicat
35250 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
35260 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a that is passed.
35270 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ** through as th
35280 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
35290 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e to the collatin
352a0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
352b0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ack..**.** ^The
352c0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 fifth argument,
352d0 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 xCallback, is a
352e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 pointer to the c
352f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
35300 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 n..** ^Multiple
35310 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
35320 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 ons can be regis
35330 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 tered using the
35340 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a same name but.**
35350 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 with different
35360 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 eTextRep paramet
35370 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 ers and SQLite w
35380 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 ill use whicheve
35390 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 r.** function re
353a0 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 quires the least
353b0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 amount of data
353c0 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a transformation..
353d0 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c ** ^If the xCall
353e0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 back argument is
353f0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 NULL then the c
35400 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
35410 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e n is.** deleted.
35420 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c ^When all coll
35430 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 ating functions
35440 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 having the same
35450 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 name are deleted
35460 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 ,.** that collat
35470 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 ion is no longer
35480 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e usable..**.** ^
35490 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 The collating fu
354a0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 nction callback
354b0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 is invoked with
354c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 a copy of the pA
354d0 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 rg .** applicati
354e0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 on data pointer
354f0 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 and with two str
35500 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f ings in the enco
35510 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a ding specified.*
35520 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 * by the eTextRe
35530 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 p argument. The
35540 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
35550 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 ion must return
35560 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 an.** integer th
35570 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 at is negative,
35580 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 zero, or positiv
35590 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 e.** if the firs
355a0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 t string is less
355b0 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c than, equal to,
355c0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
355d0 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 the second,.**
355e0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 respectively. A
355f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
35600 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 ion must always
35610 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 return the same
35620 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 answer.** given
35630 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e the same inputs.
35640 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 If two or more
35650 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
35660 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 ions are registe
35670 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 red.** to the sa
35680 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d me collation nam
35690 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 e (using differe
356a0 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 nt eTextRep valu
356b0 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 es) then all.**
356c0 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 must give an equ
356d0 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 ivalent answer w
356e0 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 hen invoked with
356f0 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 equivalent stri
35700 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c ngs..** The coll
35710 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d ating function m
35720 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c ust obey the fol
35730 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 lowing propertie
35740 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 s for all.** str
35750 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 ings A, B, and C
35760 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
35770 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 <li> If A==B the
35780 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 n B==A..** <li>
35790 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 If A==B and B==C
357a0 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c then A==C..** <
357b0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 li> If A<B TH
357c0 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c EN B>A..** <l
357d0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 i> If A<B and
357e0 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c B<C then A&l
357f0 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a t;C..** </ol>.**
35800 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 .** If a collati
35810 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c ng function fail
35820 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f s any of the abo
35830 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 ve constraints a
35840 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 nd that.** colla
35850 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
35860 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 registered and
35870 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 used, then the
35880 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
35890 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e te.** is undefin
358a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
358b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
358c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 llation_v2() wor
358d0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f ks like sqlite3_
358e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
358f0 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 ().** with the a
35900 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 ddition that the
35910 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 xDestroy callba
35920 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e ck is invoked on
35930 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 pArg when.** th
35940 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
35950 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e tion is deleted.
35960 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 .** ^Collating f
35970 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c unctions are del
35980 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 eted when they a
35990 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 re overridden by
359a0 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 later.** calls
359b0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e to the collation
359c0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 creation functi
359d0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a ons or when the.
359e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
359f0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 nection] is clos
35a00 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
35a10 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 3_close()]..**.*
35a20 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 * ^The xDestroy
35a30 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e callback is <u>n
35a40 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 ot</u> called if
35a50 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 the .** sqlite3
35a60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
35a70 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 n_v2() function
35a80 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 fails. Applicat
35a90 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 ions that invoke
35aa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 .** sqlite3_crea
35ab0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
35ac0 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c ) with a non-NUL
35ad0 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d L xDestroy argum
35ae0 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 ent should .** c
35af0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
35b00 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 code and dispose
35b10 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
35b20 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
35b30 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 .** themselves r
35b40 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 ather than expec
35b50 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 ting SQLite to d
35b60 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 eal with it for
35b70 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 them..** This is
35b80 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
35b90 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 every other SQLi
35ba0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 te interface. T
35bb0 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 he inconsistency
35bc0 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e .** is unfortun
35bd0 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 ate but cannot b
35be0 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 e changed withou
35bf0 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 t breaking backw
35c00 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 ards .** compati
35c10 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 bility..**.** Se
35c20 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 e also: [sqlite
35c30 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
35c40 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ed()] and [sqlit
35c50 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
35c60 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c ded16()]..*/.SQL
35c70 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
35c80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
35c90 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a tion(. sqlite3*
35ca0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
35cb0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
35cc0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
35cd0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 *pArg,. int(*x
35ce0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
35cf0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
35d00 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a nt,const void*).
35d10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
35d20 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
35d30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
35d40 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
35d50 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
35d60 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
35d70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
35d80 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
35d90 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
35da0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
35db0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 t void*),. void
35dc0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
35dd0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
35de0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
35df0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
35e00 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
35e10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d const void *zNam
35e20 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 e,. int eTextRe
35e30 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 p, . void *pArg
35e40 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
35e50 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
35e60 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
35e70 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
35e80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
35e90 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 llation Needed C
35ea0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
35eb0 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 To avoid having
35ec0 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 to register all
35ed0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
35ee0 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 ces before a dat
35ef0 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 abase.** can be
35f00 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 used, a single c
35f10 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
35f20 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 may be register
35f30 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
35f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
35f50 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b ion] to be invok
35f60 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 ed whenever an u
35f70 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
35f80 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 on.** sequence i
35f90 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a s required..**.*
35fa0 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 * ^If the functi
35fb0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 on is registered
35fc0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
35fd0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
35fe0 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 ded() API,.** th
35ff0 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 en it is passed
36000 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 the names of und
36010 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
36020 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 sequences as st
36030 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 rings.** encoded
36040 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 in UTF-8. ^If s
36050 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
36060 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 _needed16() is u
36070 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 sed,.** the name
36080 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 s are passed as
36090 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e UTF-16 in machin
360a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
360b0 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 der..** ^A call
360c0 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 to either functi
360d0 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 on replaces the
360e0 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 existing collati
360f0 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 on-needed callba
36100 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e ck..**.** ^(When
36110 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
36120 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 invoked, the fi
36130 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 rst argument pas
36140 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a sed is a copy.**
36150 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
36160 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
36170 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
36180 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 ded() or.** sqli
36190 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
361a0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 eded16(). The s
361b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
361c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a s the database.*
361d0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 * connection. T
361e0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
361f0 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c t is one of [SQL
36200 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 ITE_UTF8], [SQLI
36210 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 TE_UTF16BE],.**
36220 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 or [SQLITE_UTF16
36230 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 LE], indicating
36240 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 the most desirab
36250 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 le form of the c
36260 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 ollation.** sequ
36270 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 ence function re
36280 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 quired. The fou
36290 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
362a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
362b0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c .** required col
362c0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e lation sequence.
362d0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c )^.**.** The cal
362e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 lback function s
362f0 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 hould register t
36300 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 he desired colla
36310 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
36320 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
36330 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c llation()], [sql
36340 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
36350 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a ation16()], or.*
36360 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
36370 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
36380 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
36390 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c int sqlite3_col
363a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 lation_needed(.
363b0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f sqlite3*, . vo
363c0 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 id*, . void(*)(
363d0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 void*,sqlite3*,i
363e0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 nt eTextRep,cons
363f0 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 t char*).);.SQLI
36400 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
36410 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
36420 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ded16(. sqlite3
36430 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 *, . void*,. v
36440 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
36450 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 ite3*,int eTextR
36460 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a ep,const void*).
36470 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 );..#ifdef SQLIT
36480 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a E_HAS_CODEC./*.*
36490 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 * Specify the ke
364a0 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 y for an encrypt
364b0 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 ed database. Th
364c0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c is routine shoul
364d0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 d be.** called r
364e0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 ight after sqlit
364f0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a e3_open()..**.**
36500 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 The code to imp
36510 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 lement this API
36520 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 is not available
36530 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 in the public r
36540 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c elease.** of SQL
36550 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ite..*/.SQLITE_A
36560 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b PI int sqlite3_k
36570 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 ey(. sqlite3 *d
36580 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
36590 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
365a0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a to be rekeyed *
365b0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
365c0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 pKey, int nKey
365d0 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f /* The key */
365e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 .);../*.** Chang
365f0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 e the key on an
36600 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 open database.
36610 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 If the current d
36620 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a atabase is not.*
36630 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 * encrypted, thi
36640 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 s routine will e
36650 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 ncrypt it. If p
36660 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d New==0 or nNew==
36670 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 0, the.** databa
36680 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e se is decrypted.
36690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
366a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 to implement thi
366b0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 s API is not ava
366c0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 ilable in the pu
366d0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 blic release.**
366e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 of SQLite..*/.SQ
366f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
36700 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 ite3_rekey(. sq
36710 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
36720 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
36730 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
36740 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
36750 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e t void *pKey, in
36760 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 t nKey /* Th
36770 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a e new key */.);.
36780 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 ./*.** Specify t
36790 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 he activation ke
367a0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 y for a SEE data
367b0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a base. Unless .*
367c0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e * activated, non
367d0 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 e of the SEE rou
367e0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e tines will work.
367f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
36800 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 oid sqlite3_acti
36810 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 vate_see(. cons
36820 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 t char *zPassPhr
36830 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 ase /* Ac
36840 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 tivation phrase
36850 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 */.);.#endif..#i
36860 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 fdef SQLITE_ENAB
36870 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 LE_CEROD./*.** S
36880 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 pecify the activ
36890 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 ation key for a
368a0 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 CEROD database.
368b0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 Unless .** acti
368c0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 vated, none of t
368d0 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 he CEROD routine
368e0 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a s will work..*/.
368f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
36900 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
36910 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 _cerod(. const
36920 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 char *zPassPhras
36930 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 e /* Acti
36940 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f vation phrase */
36950 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a .);.#endif../*.*
36960 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 * CAPI3REF: Susp
36970 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
36980 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a r A Short Time.*
36990 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
369a0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f _sleep() functio
369b0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 n causes the cur
369c0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 rent thread to s
369d0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
369e0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 .** for at least
369f0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c a number of mil
36a00 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 liseconds specif
36a10 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d ied in its param
36a20 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 eter..**.** If t
36a30 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
36a40 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 tem does not sup
36a50 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 port sleep reque
36a60 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c sts with.** mill
36a70 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 isecond time res
36a80 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 olution, then th
36a90 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 e time will be r
36aa0 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 ounded up to.**
36ab0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f the nearest seco
36ac0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f nd. The number o
36ad0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f f milliseconds o
36ae0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 f sleep actually
36af0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 .** requested fr
36b00 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 om the operating
36b10 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 system is retur
36b20 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ned..**.** ^SQLi
36b30 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
36b40 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 is interface by
36b50 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 calling the xSle
36b60 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f ep().** method o
36b70 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
36b80 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
36b90 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 ct. If the xSle
36ba0 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f ep() method.** o
36bb0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
36bc0 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 S is not impleme
36bd0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 nted correctly,
36be0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 or not implement
36bf0 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 ed at.** all, th
36c00 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
36c10 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 of sqlite3_sleep
36c20 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 () may deviate f
36c30 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 rom the descript
36c40 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 ion.** in the pr
36c50 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
36c60 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
36c70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 int sqlite3_sle
36c80 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ep(int);../*.**
36c90 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
36ca0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c f The Folder Hol
36cb0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 ding Temporary F
36cc0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 iles.**.** ^(If
36cd0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 this global vari
36ce0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 able is made to
36cf0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
36d00 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 g which is.** th
36d10 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 e name of a fold
36d20 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 er (a.k.a. direc
36d30 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 tory), then all
36d40 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a temporary files.
36d50 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 ** created by SQ
36d60 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 Lite when using
36d70 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 a built-in [sqli
36d80 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a te3_vfs | VFS].*
36d90 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 * will be placed
36da0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f in that directo
36db0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 ry.)^ ^If this
36dc0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 variable.** is a
36dd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 NULL pointer, t
36de0 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f hen SQLite perfo
36df0 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 rms a search for
36e00 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a an appropriate.
36e10 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
36e20 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a e directory..**.
36e30 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 ** It is not saf
36e40 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 e to read or mod
36e50 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
36e60 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f e in more than o
36e70 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 ne.** thread at
36e80 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e a time. It is n
36e90 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 ot safe to read
36ea0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 or modify this v
36eb0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 ariable.** if a
36ec0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36ed0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 tion] is being u
36ee0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 sed at the same
36ef0 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 time in a separa
36f00 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a te.** thread..**
36f10 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 It is intended
36f20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
36f30 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a le be set once.*
36f40 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f * as part of pro
36f50 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 cess initializat
36f60 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 ion and before a
36f70 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
36f80 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ace.** routines
36f90 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
36fa0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 and that this v
36fb0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 ariable remain u
36fc0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 nchanged.** ther
36fd0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eafter..**.** ^T
36fe0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
36ff0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
37000 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 may modify this
37010 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 variable and ca
37020 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 use.** it to poi
37030 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 nt to memory obt
37040 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
37050 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 te3_malloc]. ^F
37060 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 urthermore,.** t
37070 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
37080 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
37090 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 always assumes
370a0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a that any string.
370b0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 ** that this var
370c0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 iable points to
370d0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 is held in memor
370e0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
370f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
37100 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 loc] and the pra
37110 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 gma may attempt
37120 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d to free that mem
37130 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 ory.** using [sq
37140 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 lite3_free]..**
37150 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 Hence, if this v
37160 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 ariable is modif
37170 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 ied directly, ei
37180 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 ther it should b
37190 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f e.** made NULL o
371a0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 r made to point
371b0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
371c0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
371d0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 _malloc].** or e
371e0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 lse the use of t
371f0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
37200 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
37210 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 should be avoid
37220 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ed..**.** <b>Not
37230 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e e to Windows Run
37240 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 time users:</b>
37250 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 The temporary d
37260 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 irectory must be
37270 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f set.** prior to
37280 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
37290 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 3_open] or [sqli
372a0 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f te3_open_v2]. O
372b0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 therwise, variou
372c0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 s.** features th
372d0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 at require the u
372e0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 se of temporary
372f0 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 files may fail.
37300 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 Here is an.** e
37310 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f xample of how to
37320 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43 do this using C
37330 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e 64 ++ with the Wind
37340 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a ows Runtime:.**.
37350 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
37360 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 pre>.** LPCWSTR
37370 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a zPath = Windows:
37380 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 :Storage::Applic
37390 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 ationData::Curre
373a0 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 nt->.**
373b0 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 TemporaryFold
373c0 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 er->Path->Data()
373d0 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42 ;.** char zPathB
373e0 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 uf[MAX_PATH
373f0 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d + 1];.** mem
37400 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c set(zPathBuf, 0,
37410 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 sizeof(zPathBuf
37420 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 ));.** WideCharT
37430 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54 oMultiByte(CP_UT
37440 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 F8, 0, zPath, -1
37450 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65 , zPathBuf, size
37460 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a of(zPathBuf),.**
37470 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c NULL
37480 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 , NULL);.** sqli
37490 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f te3_temp_directo
374a0 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 ry = sqlite3_mpr
374b0 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68 intf("%s", zPath
374c0 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c Buf);.** </pre><
374d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a /blockquote>.*/.
374e0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
374f0 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 E_EXTERN char *s
37500 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
37510 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ctory;../*.** CA
37520 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
37530 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 The Folder Holdi
37540 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 ng Database File
37550 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 s.**.** ^(If thi
37560 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c s global variabl
37570 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 e is made to poi
37580 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 nt to a string w
37590 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e hich is.** the n
375a0 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 ame of a folder
375b0 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 (a.k.a. director
375c0 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 y), then all dat
375d0 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 abase files.** s
375e0 70 65 63 69 66 69 65 64 20 77 69 74 68 20 61 20 pecified with a
375f0 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d relative pathnam
37600 65 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72 e and created or
37610 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 accessed by.**
37620 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e SQLite when usin
37630 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e g a built-in win
37640 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 dows [sqlite3_vf
37650 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 s | VFS] will be
37660 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 assumed.** to b
37670 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 e relative to th
37680 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 at directory.)^
37690 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c ^If this variabl
376a0 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 e is a NULL.** p
376b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
376c0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ite assumes that
376d0 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 all database fi
376e0 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a les specified.**
376f0 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 with a relative
37700 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65 pathname are re
37710 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 63 75 lative to the cu
37720 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a rrent directory.
37730 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65 ** for the proce
37740 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 ss. Only the wi
37750 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20 ndows VFS makes
37760 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 use of this glob
37770 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 al.** variable;
37780 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79 it is ignored by
37790 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a the unix VFS..*
377a0 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 *.** Changing th
377b0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 e value of this
377c0 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61 variable while a
377d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
377e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 tion is.** open
377f0 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20 can result in a
37800 63 6f 72 72 75 70 74 20 64 61 74 61 62 61 73 65 corrupt database
37810 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ..**.** It is no
37820 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
37830 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
37840 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 riable in more t
37850 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 han one.** threa
37860 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 d at a time. It
37870 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
37880 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
37890 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 his variable.**
378a0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 if a [database c
378b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
378c0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 ing used at the
378d0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 same time in a s
378e0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 eparate.** threa
378f0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 d..** It is inte
37900 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 nded that this v
37910 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f ariable be set o
37920 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f nce.** as part o
37930 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 f process initia
37940 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 lization and bef
37950 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 ore any SQLite i
37960 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 nterface.** rout
37970 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 ines have been c
37980 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 alled and that t
37990 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d his variable rem
379a0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a ain unchanged.**
379b0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a thereafter..**.
379c0 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 ** ^The [data_st
379d0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
379e0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 agma] may modify
379f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 this variable a
37a00 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 nd cause.** it t
37a10 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
37a20 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
37a30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
37a40 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c . ^Furthermore,
37a50 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74 .** the [data_st
37a60 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
37a70 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 agma] always ass
37a80 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 umes that any st
37a90 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 ring.** that thi
37aa0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 s variable point
37ab0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 s to is held in
37ac0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
37ad0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
37ae0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 3_malloc] and th
37af0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 e pragma may att
37b00 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 empt to free tha
37b10 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e t memory.** usin
37b20 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d g [sqlite3_free]
37b30 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 ..** Hence, if t
37b40 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 his variable is
37b50 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c modified directl
37b60 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f y, either it sho
37b70 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e uld be.** made N
37b80 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 ULL or made to p
37b90 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
37ba0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
37bb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a lite3_malloc].**
37bc0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 or else the use
37bd0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74 of the [data_st
37be0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
37bf0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 agma] should be
37c00 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 avoided..*/.SQLI
37c10 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 TE_API SQLITE_EX
37c20 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 TERN char *sqlit
37c30 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f 72 e3_data_director
37c40 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 y;../*.** CAPI3R
37c50 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 EF: Test For Aut
37c60 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a o-Commit Mode.**
37c70 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f KEYWORDS: {auto
37c80 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a commit mode}.**.
37c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37ca0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 get_autocommit()
37cb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
37cc0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a ns non-zero or.*
37cd0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 * zero if the gi
37ce0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e ven database con
37cf0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 nection is or is
37d00 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d not in autocomm
37d10 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 it mode,.** resp
37d20 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f ectively. ^Auto
37d30 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f commit mode is o
37d40 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a n by default..**
37d50 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
37d60 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
37d70 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 a [BEGIN] state
37d80 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f ment..** ^Autoco
37d90 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d mmit mode is re-
37da0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f enabled by a [CO
37db0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 MMIT] or [ROLLBA
37dc0 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 CK]..**.** If ce
37dd0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 rtain kinds of e
37de0 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 rrors occur on a
37df0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
37e00 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d n a multi-statem
37e10 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 ent.** transacti
37e20 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 on (errors inclu
37e30 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c ding [SQLITE_FUL
37e40 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 L], [SQLITE_IOER
37e50 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e R],.** [SQLITE_N
37e60 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 OMEM], [SQLITE_B
37e70 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 USY], and [SQLIT
37e80 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 E_INTERRUPT]) th
37e90 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 en the.** transa
37ea0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 ction might be r
37eb0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
37ec0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f atically. The o
37ed0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 nly way to.** fi
37ee0 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 nd out whether S
37ef0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
37f00 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 lly rolled back
37f10 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
37f20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f after.** an erro
37f30 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 r is to use this
37f40 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
37f50 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 If another thre
37f60 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 ad changes the a
37f70 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 utocommit status
37f80 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
37f90 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 .** connection w
37fa0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e hile this routin
37fb0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 e is running, th
37fc0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
37fd0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 lue.** is undefi
37fe0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ned..*/.SQLITE_A
37ff0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 PI int sqlite3_g
38000 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 et_autocommit(sq
38010 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
38020 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 CAPI3REF: Find T
38030 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 he Database Hand
38040 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 le Of A Prepared
38050 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a Statement.**.**
38060 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 ^The sqlite3_db
38070 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 _handle interfac
38080 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 e returns the [d
38090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
380a0 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f on] handle.** to
380b0 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 which a [prepar
380c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 ed statement] be
380d0 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 longs. ^The [da
380e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
380f0 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 n].** returned b
38100 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e y sqlite3_db_han
38110 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 dle is the same
38120 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
38130 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 tion].** that wa
38140 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
38150 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ment.** to the [
38160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
38170 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 v2()] call (or i
38180 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 ts variants) tha
38190 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a t was used to.**
381a0 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 create the stat
381b0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 ement in the fir
381c0 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c st place..*/.SQL
381d0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 ITE_API sqlite3
381e0 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 *sqlite3_db_hand
381f0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
38200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
38210 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 EF: Return The F
38220 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 ilename For A Da
38230 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
38240 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c n.**.** ^The sql
38250 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 ite3_db_filename
38260 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (D,N) interface
38270 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
38280 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a r to a filename.
38290 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
382a0 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 th database N of
382b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 connection D.
382c0 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 ^The main databa
382d0 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 se file.** has t
382e0 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 he name "main".
382f0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 If there is no
38300 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
38310 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 e N on the datab
38320 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
38330 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 n D, or if datab
38340 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f ase N is a tempo
38350 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 rary or in-memor
38360 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e y database, then
38370 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
38380 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
38390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e **.** ^The filen
383a0 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 ame returned by
383b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 this function is
383c0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 the output of t
383d0 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e he.** xFullPathn
383e0 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ame method of th
383f0 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 e [VFS]. ^In ot
38400 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 her words, the f
38410 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 ilename.** will
38420 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 be an absolute p
38430 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 athname, even if
38440 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 the filename us
38450 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 ed.** to open th
38460 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 e database origi
38470 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 nally was a URI
38480 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 or relative path
38490 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f name..*/.SQLITE_
384a0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
384b0 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e sqlite3_db_filen
384c0 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c ame(sqlite3 *db,
384d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
384e0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Name);../*.** CA
384f0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
38500 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 e if a database
38510 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a is read-only.**.
38520 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
38530 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 db_readonly(D,N)
38540 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
38550 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61 ns 1 if the data
38560 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e base N.** of con
38570 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61 nection D is rea
38580 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 d-only, 0 if it
38590 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f is read/write, o
385a0 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 r -1 if N is not
385b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
385c0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f a database on co
385d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 nnection D..*/.S
385e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
385f0 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c lite3_db_readonl
38600 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 y(sqlite3 *db, c
38610 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
38620 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 me);../*.** CAPI
38630 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 3REF: Find the n
38640 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 ext prepared sta
38650 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 tement.**.** ^Th
38660 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
38670 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
38680 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 o the next [prep
38690 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
386a0 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 after.** pStmt a
386b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
386c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
386d0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e nection] pDb. ^
386e0 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c If pStmt is NULL
386f0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e .** then this in
38700 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
38710 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
38720 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 first prepared
38730 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 statement.** ass
38740 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
38750 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
38760 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e tion pDb. ^If n
38770 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 o prepared state
38780 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 ment.** satisfie
38790 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 s the conditions
387a0 20 6f 66 20 74 68 69 73 20 72 6f 75 74