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 34 22 0a 23 64 65 66 69 6e 65 20 53 .7.14".#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 34 0a 23 64 65 MBER 3007014.#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 32 CE_ID "2012
1070: 2d 30 39 2d 30 33 20 31 31 3a 33 39 3a 35 39 20 -09-03 11:39:59
1080: 61 31 35 61 37 30 38 34 30 65 31 61 66 35 35 66 a15a70840e1af55f
1090: 66 65 34 30 33 35 66 35 33 65 38 39 34 61 32 64 fe4035f53e894a2d
10a0: 35 38 32 64 38 66 37 34 22 0a 0a 2f 2a 0a 2a 2a 582d8f74"../*.**
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 28 29 20 69 73 lite3_close() is
2fc0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 called on a [da
2fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2fe0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 n] that still ha
2ff0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 s.** outstanding
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a ndles], and/or.*
3030: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 * [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 p] objects then
3050: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 it returns SQLIT
3060: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61 E_OK but the dea
3070: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
3080: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 resources is def
3090: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 erred until all
30a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
30b0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e ents], [BLOB han
30c0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 dles],.** and [s
30d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
30e0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 bjects are also
30f0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a destroyed..**.**
3100: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 ^If an [sqlite3
3110: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 ] object is dest
3120: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 royed while a tr
3130: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 ansaction is ope
3140: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 n,.** the transa
3150: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 ction is automat
3160: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 ically rolled ba
3170: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 ck..**.** The C
3180: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
3190: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 lite3_close(C)]
31a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
31b0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 se_v2(C)].** mus
31c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 t be either a NU
31d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 LL.** pointer or
31e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 an [sqlite3] ob
31f0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 ject pointer obt
3200: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
3210: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
3230: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
3240: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 e3_open_v2()], a
3250: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c nd not previousl
3260: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 y closed..** ^Ca
3270: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c lling sqlite3_cl
3280: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ose() or sqlite3
3290: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 _close_v2() with
32a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
32b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 ** argument is a
32c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
32d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
32e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nt sqlite3_close
32f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
3300: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
3310: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 e3_close_v2(sqli
3320: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 te3*);../*.** Th
3330: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c e type for a cal
3340: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a lback function..
3350: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 ** This is legac
3360: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 y and deprecated
3370: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 . It is include
3380: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c d for historical
3390: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
33a0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 y and is not doc
33b0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 umented..*/.type
33c0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 def int (*sqlite
33d0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 3_callback)(void
33e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 *,int,char**, ch
33f0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ar**);../*.** CA
3400: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 PI3REF: One-Step
3410: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e Query Execution
3420: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a Interface.**.**
3430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 The sqlite3_exe
3440: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 c() interface is
3450: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 a convenience w
3460: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a rapper around.**
3470: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
3480: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
3490: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 3_step()], and [
34a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
34b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c ()],.** that all
34c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 ows an applicati
34d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 on to run multip
34e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 le statements of
34f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 SQL.** without
3500: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 having to use a
3510: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a lot of C code. .
3520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 e3_exec() interf
3540: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 ace runs zero or
3550: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f more UTF-8 enco
3560: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f ded,.** semicolo
3570: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 n-separate SQL s
3580: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 tatements passed
3590: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 into its 2nd ar
35a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 gument,.** in th
35b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 e context of the
35c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
35d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e ction] passed in
35e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 as its 1st.** a
35f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 rgument. ^If th
3600: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
3610: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 ion of the 3rd a
3620: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
3630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 not NULL, then i
3650: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 t is invoked for
3660: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 each result row
3670: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f .** coming out o
3680: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 f the evaluated
3690: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 SQL statements.
36a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 ^The 4th argume
36b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
36c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 _exec() is relay
36d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ed through to th
36e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f e 1st argument o
36f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 f each.** callba
3700: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 ck invocation.
3710: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
3720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
3730: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
3740: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 NULL, then no c
3750: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 allback is ever
3760: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 invoked and resu
3770: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 lt rows are.** i
3780: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 gnored..**.** ^I
3790: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
37a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 s while evaluati
37b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ng the SQL state
37c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
37d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
37e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 c(), then execut
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 ion of the curre
3800: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f nt statement sto
3810: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 ps and.** subseq
3820: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 uent statements
3830: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 are skipped. ^I
3840: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
3850: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3860: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 xec().** is not
3870: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 NULL then any er
3880: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 ror message is w
3890: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
38a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ry obtained.** f
38b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
38c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 loc()] and passe
38d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 d back through t
38e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
38f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 ..** To avoid me
3900: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 mory leaks, the
3910: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
3920: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ld invoke [sqlit
3930: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e e3_free()].** on
3940: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
3950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
3960: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
3970: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 parameter of.**
3980: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 of sqlite3_exec(
3990: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f ) after the erro
39a0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
39b0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 is no longer ne
39c0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 eded..** ^If the
39d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
39e0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
39f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 is not NULL and
3a00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 no errors.** oc
3a10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 cur, then sqlite
3a20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 3_exec() sets th
3a30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 e pointer in its
3a40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
3a50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 o.** NULL before
3a60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a returning..**.*
3a70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 * ^If an sqlite3
3a80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3a90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
3aa0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 o, the sqlite3_e
3ab0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 xec().** routine
3ac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
3ad0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e ABORT without in
3ae0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 voking the callb
3af0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a ack again and.**
3b00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 without running
3b10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 any subsequent
3b20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
3b30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 **.** ^The 2nd a
3b40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
3b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
3b70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
3b80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
3b90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 he result. ^The
3ba0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 3rd argument to
3bb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 the sqlite3_exe
3bc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 c().** callback
3bd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3be0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3bf0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 gs obtained as i
3c00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 f from.** [sqlit
3c10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
3c20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 ], one for each
3c30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 column. ^If an
3c40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 element of a.**
3c50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 result row is NU
3c60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 LL then the corr
3c70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 esponding string
3c80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
3c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3ca0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3cb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
3cc0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
3cd0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 t to the.** sqli
3ce0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3cf0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 ack is an array
3d00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 of pointers to s
3d10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 trings where eac
3d20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 h.** entry repre
3d30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f sents the name o
3d40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 f corresponding
3d50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 result column as
3d60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
3d70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d m [sqlite3_colum
3d80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_name()]..**.**
3d90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 ^If the 2nd par
3da0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3db0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 3_exec() is a NU
3dc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f LL pointer, a po
3dd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 inter.** to an e
3de0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 mpty string, or
3df0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 a pointer that c
3e00: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 ontains only whi
3e10: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a tespace and/or .
3e20: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c ** SQL comments,
3e30: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 then no SQL sta
3e40: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c tements are eval
3e50: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 uated and the da
3e60: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 tabase.** is not
3e70: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 changed..**.**
3e80: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a Restrictions:.**
3e90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
3ea0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3eb0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 must insure tha
3ec0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 t the 1st parame
3ed0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3ee0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 xec().** is
3ef0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 a valid and ope
3f00: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
3f10: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e ection]..** <li>
3f20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3f30: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 must not close
3f40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3f50: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
3f60: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 by.** the 1
3f70: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
3f80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 sqlite3_exec() w
3f90: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 hile sqlite3_exe
3fa0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a c() is running..
3fb0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
3fc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
3fd0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 modify the SQL
3fe0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 statement text p
3ff0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 assed into.**
4000: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d the 2nd param
4010: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
4020: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c exec() while sql
4030: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
4040: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e unning..** </ul>
4050: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
4060: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 nt sqlite3_exec(
4070: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 . 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 2f 2a /*
40a0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
40b0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
40c0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 r *sql,
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40e0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
40f0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e valuated */. in
4100: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f t (*callback)(vo
4110: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 id*,int,char**,c
4120: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c har**), /* Call
4130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f back function */
4140: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
4170: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 1st argument to
4180: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 callback */. c
4190: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 har **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 2f 2a 20 45 72 72 /* Err
41c0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
41d0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ere */.);../*.**
41e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
41f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f t Codes.** KEYWO
4200: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b RDS: SQLITE_OK {
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 error code} {err
4220: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 or codes}.** KEY
4230: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 WORDS: {result c
4240: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 ode} {result cod
4250: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 es}.**.** Many S
4260: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
4270: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
4280: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
4290: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
42a0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 .** here in orde
42b0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 r to indicate su
42c0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
42d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
42e0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
42f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
4300: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4310: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
4320: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
4330: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
4340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a result codes],.
4350: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 ** [sqlite3_vtab
4360: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 _on_conflict()]
4370: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b [SQLITE_ROLLBACK
4380: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d | result codes]
4390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
43a0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
43b0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
43c0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
43d0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
43e0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
43f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
4400: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
4410: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
4420: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
4430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4440: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
4450: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
4460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
4480: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
4490: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
44a0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
44b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
44c0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
44d0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
44e0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
44f0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
4510: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
4520: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
4530: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4550: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
4560: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
4570: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
4590: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
45a0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
45b0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
45d0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
45e0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
45f0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
4600: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
4620: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
4630: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
4640: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
4650: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4670: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
4680: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
4690: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
46a0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
46b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
46c0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
46d0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
46e0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
46f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4700: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
4710: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 /* Unknown opc
4720: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 ode in sqlite3_f
4730: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f ile_control() */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4750: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 FULL 13
4760: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 /* Insertion fa
4770: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 iled because dat
4780: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f abase is full */
4790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
47a0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 CANTOPEN 14
47b0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 /* Unable to op
47c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
47d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
47e0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 SQLITE_PROTOCOL
47f0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 15 /* Datab
4800: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f ase lock protoco
4810: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 l error */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 ne SQLITE_EMPTY
4830: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 16 /* Da
4840: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 tabase is empty
4850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4860: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 E_SCHEMA 17
4870: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
4880: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 se schema change
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
48a0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 ITE_TOOBIG
48b0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 18 /* String o
48c0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 r BLOB exceeds s
48d0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 ize limit */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
48f0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 TRAINT 19 /*
4900: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e Abort due to con
4910: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
4920: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
4930: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 ITE_MISMATCH
4940: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 20 /* Data typ
4950: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 e mismatch */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 efine SQLITE_MIS
4970: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a USE 21 /*
4980: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e Library used in
4990: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 correctly */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 fine SQLITE_NOLF
49b0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 S 22 /*
49c0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 Uses OS features
49d0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f not supported o
49e0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e n host */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 e SQLITE_AUTH
4a00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 23 /* Aut
4a10: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 horization denie
4a20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4a30: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 ITE_FORMAT
4a40: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 24 /* Auxiliar
4a50: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 y database forma
4a60: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 t error */.#defi
4a70: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 ne SQLITE_RANGE
4a80: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 25 /* 2n
4a90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
4aa0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 qlite3_bind out
4ab0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 of range */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 ine SQLITE_NOTAD
4ad0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 B 26 /* F
4ae0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 ile opened that
4af0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
4b00: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 e SQLITE_ROW
4b20: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 100 /* sql
4b30: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
4b40: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 another row read
4b50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4b60: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 ITE_DONE
4b70: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 101 /* sqlite3_
4b80: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 step() has finis
4b90: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f hed executing */
4ba0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 ./* end-of-error
4bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a -codes */../*.**
4bc0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e CAPI3REF: Exten
4bd0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
4be0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
4bf0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
4c00: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 de} {extended er
4c10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 ror codes}.** KE
4c20: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 YWORDS: {extende
4c30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b d result code} {
4c40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4c50: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 codes}.**.** In
4c60: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4c70: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4c80: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4c90: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 eturn one of 26
4ca0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 integer.** [SQLI
4cb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 TE_OK | result c
4cc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c odes]. However,
4cd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 experience has
4ce0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 shown that many
4cf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 of.** these resu
4d00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f lt codes are too
4d10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e coarse-grained.
4d20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 They do not pr
4d30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 ovide as.** much
4d40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
4d50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 ut problems as p
4d60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 rogrammers might
4d70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 like. In an ef
4d80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 fort to.** addre
4d90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 ss this, newer v
4da0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4db0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 e (version 3.3.8
4dc0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c and later) incl
4dd0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 ude.** support f
4de0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 or additional re
4df0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 sult codes that
4e00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 provide more det
4e10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f ailed informatio
4e20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 n.** about error
4e30: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 s. The extended
4e40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4e50: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
4e60: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 bled.** on a per
4e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
4e80: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 tion basis using
4e90: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4ea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
4eb0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a _codes()] API..*
4ec0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 *.** Some of the
4ed0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e available exten
4ee0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4ef0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 are listed here
4f00: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 ..** One may exp
4f10: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ect the number o
4f20: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c f extended resul
4f30: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 t codes will be
4f40: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 expand.** over t
4f50: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 ime. Software t
4f60: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 hat uses extende
4f70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 d result codes s
4f80: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 hould expect.**
4f90: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c to see new resul
4fa0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 t codes in futur
4fb0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
4fc0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
4fd0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 SQLITE_OK result
4fe0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 code will never
4ff0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 be extended. I
5000: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a t will always.**
5010: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f be exactly zero
5020: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
5080: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5130: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5170: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
51b0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
51f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
5200: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5210: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
5220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5230: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
5240: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5250: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5270: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5290: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
52b0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
52c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
52d0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
52f0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5310: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5330: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5350: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5370: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
5380: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
5390: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
53b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
53d0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
53f0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5410: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5430: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5450: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5470: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5490: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54b0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54d0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54f0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5510: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5530: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
5540: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5550: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5570: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5590: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
55b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
55d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
55f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
5600: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
5610: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
5630: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 TOPEN_NOTEMPDIR
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
5650: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a TOPEN | (1<<8)).
5660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5670: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 ANTOPEN_ISDIR
5680: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5690: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 ANTOPEN | (2<<8)
56a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
56b0: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 _CORRUPT_VTAB
56c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
56d0: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 _CORRUPT | (1<<8
56e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
56f0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 E_READONLY_RECOV
5700: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 ERY (SQLIT
5710: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c E_READONLY | (1<
5720: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5730: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e ITE_READONLY_CAN
5740: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c TLOCK (SQL
5750: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
5760: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5770: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c QLITE_ABORT_ROLL
5780: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 BACK (S
5790: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 QLITE_ABORT | (2
57a0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 <<8))../*.** CAP
57b0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 I3REF: Flags For
57c0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 File Open Opera
57d0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
57e0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 e bit values are
57f0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
5800: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 e in the.** 3rd
5810: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
5820: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
5830: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 2()] interface a
5840: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 nd.** in the 4th
5850: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
5860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
5870: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f Open] method..*/
5880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5890: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
58a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
58b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
58c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
58d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
58e0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
58f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
5900: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5910: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5930: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
5940: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
5950: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5960: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5980: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
5990: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
59a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
59b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
59c0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
59d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
59e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 OPEN_AUTOPROXY
5a10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
5a20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 OPEN_URI
5a50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
5a60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5a70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 OPEN_MEMORY
5aa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
5ab0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5ac0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ae0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
5af0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
5b00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
5b30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
5b40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
5b70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
5b80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ba0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
5bb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
5bc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5be0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
5bf0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
5c00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c20: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
5c30: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
5c40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c60: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
5c70: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
5c80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ca0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
5cb0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
5cc0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5cd0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5cf0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
5d00: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
5d10: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5d20: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5d30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5d40: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
5d50: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
5d60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5d70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5d90: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
5da0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
5db0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5dc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5de0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 OPEN_WAL
5df0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 0x00080000
5e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5e10: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 ../* Reserved:
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5e30: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 0x00F0000
5e40: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0 */../*.** CAPI
5e50: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
5e60: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a racteristics.**.
5e70: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 ** The xDeviceCh
5e80: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
5e90: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
5ea0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
5eb0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
5ec0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
5ed0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
5ee0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 of these.** bit
5ef0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
5f00: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
5f10: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
5f20: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
5f30: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
5f40: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
5f50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
5f60: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
5f70: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
5f80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5f90: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
5fa0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
5fb0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
5fc0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
5fd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5fe0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
5ff0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
6000: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
6010: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
6020: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
6030: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
6040: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
6050: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
6060: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
6070: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
6080: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
6090: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
60a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
60b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
60c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
60d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
60e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
60f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
6100: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
6110: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
6120: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
6130: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
6140: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
6150: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
6160: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
6170: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
6180: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
6190: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
61a0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
61b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
61c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
61d0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 RWRITE property
61e0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 means that.** af
61f0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f ter reboot follo
6200: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 wing a crash or
6210: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 power loss, the
6220: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a only bytes in a.
6230: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 ** file that wer
6240: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 e written at the
6250: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 application lev
6260: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 el might have ch
6270: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 anged.** and tha
6280: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 t adjacent bytes
6290: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 , even bytes wit
62a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 hin the same sec
62b0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 tor are.** guara
62c0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 nteed to be unch
62d0: 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e anged..*/.#defin
62e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
62f0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 TOMIC
6300: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
6310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 IOCAP_ATOMIC512
6330: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6340: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
6350: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6360: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 MIC1K
6370: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 0x00000004.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6390: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 CAP_ATOMIC2K
63a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
63b0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 00008.#define SQ
63c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
63d0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C4K
63e0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 0x00000010.#de
63f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6400: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 P_ATOMIC8K
6410: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6420: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 020.#define SQLI
6430: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
6440: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 6K
6450: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 0x00000040.#defi
6460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6470: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 ATOMIC32K
6480: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
6490: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
64a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b _IOCAP_ATOMIC64K
64b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
64c0: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
64d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
64e0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 FE_APPEND
64f0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 0x00000200.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6510: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
6520: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6530: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 000400.#define S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 QLITE_IOCAP_UNDE
6550: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 LETABLE_WHEN_OPE
6560: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 N 0x00000800.#d
6570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6580: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
6590: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 RWRITE 0x0000
65a0: 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 1000../*.** CAPI
65b0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 3REF: File Locki
65c0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 ng Levels.**.**
65d0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
65e0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
65f0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
6600: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
6610: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
6620: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
6630: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
6640: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
6650: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
6660: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
6670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6680: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
6690: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
66a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
66b0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
66c0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
66d0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
66e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
66f0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
6700: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
6710: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
6720: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
6730: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
6740: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
6750: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c s.**.** When SQL
6760: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ite invokes the
6770: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f xSync() method o
6780: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 f an.** [sqlite3
6790: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
67a0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f ect it uses a co
67b0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mbination of.**
67c0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
67d0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
67e0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
67f0: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
6800: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
6810: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
6820: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
6830: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
6840: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
6850: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
6860: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
6870: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
6880: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
6890: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c lushed. If the l
68a0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f ower four bits o
68b0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 f the flag.** eq
68c0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
68d0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 NORMAL, that mea
68e0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c ns to use normal
68f0: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 fsync() semanti
6900: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f cs..** If the lo
6910: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 wer four bits eq
6920: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
6930: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 FULL, that means
6940: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f .** to use Mac O
6950: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
6960: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 nc instead of fs
6970: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 ync()..**.** Do
6980: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 not confuse the
6990: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
69a0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
69b0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a NC_FULL flags.**
69c0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d with the [PRAGM
69d0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e A synchronous]=N
69e0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d ORMAL and [PRAGM
69f0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 A synchronous]=F
6a00: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e ULL.** settings.
6a10: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f The [synchrono
6a20: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 us pragma] deter
6a30: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 mines when calls
6a40: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 to the.** xSync
6a50: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 VFS method occu
6a60: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e r and applies un
6a70: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 iformly across a
6a80: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a ll platforms..**
6a90: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 The SQLITE_SYNC
6aa0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
6ab0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
6ac0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 gs determine how
6ad0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 .** energetic or
6ae0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 rigorous or for
6af0: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f ceful the sync o
6b00: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e perations are an
6b10: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 d.** only make a
6b20: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d difference on M
6b30: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 ac OSX for the d
6b40: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f efault SQLite co
6b50: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 de..** (Third-pa
6b60: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e rty VFS implemen
6b70: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c tations might al
6b80: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 so make the dist
6b90: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 inction.** betwe
6ba0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e en SQLITE_SYNC_N
6bb0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
6bc0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 _SYNC_FULL, but
6bd0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 among the.** ope
6be0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e rating systems n
6bf0: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 atively supporte
6c00: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c d by SQLite, onl
6c10: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 y Mac OSX.** car
6c20: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 es about the dif
6c30: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 ference.).*/.#de
6c40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
6c50: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 _NORMAL 0
6c60: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 x00002.#define S
6c70: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
6c80: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0x00003
6c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6ca0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 SYNC_DATAONLY
6cb0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 0x00010../*.*
6cc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
6cd0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 nterface Open Fi
6ce0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 le Handle.**.**
6cf0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
6d00: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
6d10: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
6d20: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c in the .** [sql
6d30: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e ite3_vfs | OS in
6d40: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 terface layer].
6d50: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
6d60: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c nterface.** impl
6d70: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
6d80: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
6d90: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
6da0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
6db0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
6dc0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
6dd0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
6de0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
6df0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
6e00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
6e10: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
6e20: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
6e30: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
6e40: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
6e50: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
6e60: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
6e70: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
6e80: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
6e90: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
6ea0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
6eb0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
6ec0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
6ed0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
6ee0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
6ef0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
6f00: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
6f10: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
6f20: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
6f30: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c .**.** Every fil
6f40: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 e opened by the
6f50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
6f60: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c en] method popul
6f70: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 ates an.** [sqli
6f80: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
6f90: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f (or, more commo
6fa0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 nly, a subclass
6fb0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
6fc0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 e3_file] object)
6fd0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
6fe0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
6ff0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a f this object..*
7000: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 * This object de
7010: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 fines the method
7020: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 s used to perfor
7030: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 m various operat
7040: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 ions.** against
7050: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 the open file re
7060: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 presented by the
7070: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
7080: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
7090: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
70a0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
70b0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 sets the sqlite3
70c0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
70d0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 lement .** to a
70e0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
70f0: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
7100: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 e3_io_methods.xC
7110: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d lose method.** m
7120: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 ay be invoked ev
7130: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 en if the [sqlit
7140: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 e3_vfs.xOpen] re
7150: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 ported that it f
7160: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f ailed. The.** o
7170: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 nly way to preve
7180: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c nt a call to xCl
7190: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ose following a
71a0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f failed [sqlite3_
71b0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 vfs.xOpen].** is
71c0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
71d0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 3_vfs.xOpen] to
71e0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
71f0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c file.pMethods el
7200: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c ement.** to NULL
7210: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
7220: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 s argument to xS
7230: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ync may be one o
7240: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e f [SQLITE_SYNC_N
7250: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 ORMAL] or.** [SQ
7260: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e LITE_SYNC_FULL].
7270: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 The first choi
7280: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c ce is the normal
7290: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 fsync()..** The
72a0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 second choice i
72b0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 s a Mac OS X sty
72c0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 le fullsync. Th
72d0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 e [SQLITE_SYNC_D
72e0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 ATAONLY].** flag
72f0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 may be ORed in
7300: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
7310: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f only the data o
7320: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e f the file.** an
7330: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 d not its inode
7340: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 needs to be sync
7350: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ed..**.** The in
7360: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 teger values to
7370: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
7380: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 ock() are one of
7390: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
73a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
73b0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 NE],.** <li> [SQ
73c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
73d0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
73e0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
73f0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7400: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
7410: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
7420: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
7430: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a IVE]..** </ul>.*
7440: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 * xLock() increa
7450: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 ses the lock. xU
7460: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 nlock() decrease
7470: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 s the lock..** T
7480: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 he xCheckReserve
7490: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 dLock() method c
74a0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e hecks whether an
74b0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 y database conne
74c0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 ction,.** either
74d0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 in this process
74e0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 or in some othe
74f0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f r process, is ho
7500: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 lding a RESERVED
7510: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 ,.** PENDING, or
7520: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 EXCLUSIVE lock
7530: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 on the file. It
7540: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a returns true.**
7550: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 if such a lock
7560: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 exists and false
7570: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
7580: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 * The xFileContr
7590: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 ol() method is a
75a0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 generic interfa
75b0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 ce that allows c
75c0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 ustom.** VFS imp
75d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 lementations to
75e0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c directly control
75f0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 an open file us
7600: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
7610: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
7620: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
7630: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 The second "op"
7640: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a argument is an.*
7650: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 * integer opcode
7660: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
7670: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 ument is a gener
7680: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e ic pointer inten
7690: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 ded to.** point
76a0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
76b0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 hat may contain
76c0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 arguments or spa
76d0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a ce in which to.*
76e0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 * write return v
76f0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 alues. Potentia
7700: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 l uses for xFile
7710: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 Control() might
7720: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 be.** functions
7730: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 to enable blocki
7740: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 ng locks with ti
7750: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 meouts, to chang
7760: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 e the.** locking
7770: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 strategy (for e
7780: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f xample to use do
7790: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 t-file locks), t
77a0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f o inquire.** abo
77b0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ut the status of
77c0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 a lock, or to b
77d0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 reak stale locks
77e0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a . The SQLite.**
77f0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 core reserves a
7800: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 ll opcodes less
7810: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 than 100 for its
7820: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b own use..** A [
7830: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
7840: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 KSTATE | list of
7850: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 opcodes] less t
7860: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c han 100 is avail
7870: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 able..** Applica
7880: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e tions that defin
7890: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 e a custom xFile
78a0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 Control method s
78b0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 hould use opcode
78c0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 s.** greater tha
78d0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 n 100 to avoid c
78e0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 onflicts. VFS i
78f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 mplementations s
7900: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
7910: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 [SQLITE_NOTFOUND
7920: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 ] for file contr
7930: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 ol opcodes that
7940: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 they do not.** r
7950: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 ecognize..**.**
7960: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 The xSectorSize(
7970: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 ) method returns
7980: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 the sector size
7990: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 of the.** devic
79a0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 e that underlies
79b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 the file. The
79c0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 sector size is t
79d0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 he.** minimum wr
79e0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 ite that can be
79f0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 performed withou
7a00: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 t disturbing.**
7a10: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 other bytes in t
7a20: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 he file. The xD
7a30: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
7a40: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 tics().** method
7a50: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 returns a bit v
7a60: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 ector describing
7a70: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 behaviors of th
7a80: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 e.** underlying
7a90: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 device:.**.** <u
7aa0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
7ab0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d TE_IOCAP_ATOMIC]
7ac0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
7ad0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 _IOCAP_ATOMIC512
7ae0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7af0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b E_IOCAP_ATOMIC1K
7b00: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7b10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b E_IOCAP_ATOMIC2K
7b20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b E_IOCAP_ATOMIC4K
7b40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7b50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
7b60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7b70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 E_IOCAP_ATOMIC16
7b80: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
7ba0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 2K].** <li> [SQL
7bb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7bc0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 64K].** <li> [SQ
7bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
7be0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 APPEND].** <li>
7bf0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 [SQLITE_IOCAP_SE
7c00: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 QUENTIAL].** </u
7c10: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c l>.**.** The SQL
7c20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7c30: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
7c40: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 that all writes
7c50: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 of.** any size a
7c60: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
7c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7c80: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a MICnnn values.**
7c90: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 mean that write
7ca0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 s of blocks that
7cb0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 are nnn bytes i
7cc0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 n size and.** ar
7cd0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
7ce0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 address which is
7cf0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 an integer mult
7d00: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 iple of.** nnn a
7d10: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
7d20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
7d30: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d E_APPEND value m
7d40: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 eans.** that whe
7d50: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 n data is append
7d60: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 ed to a file, th
7d70: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 e data is append
7d80: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e ed.** first then
7d90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
7da0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 file is extende
7db0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 d, never the oth
7dc0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 er.** way around
7dd0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
7de0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 CAP_SEQUENTIAL p
7df0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
7e00: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f at.** informatio
7e10: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 n is written to
7e20: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 disk in the same
7e30: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a order as calls.
7e40: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a ** to xWrite()..
7e50: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 **.** If xRead()
7e60: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
7e70: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
7e80: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 it must also fi
7e90: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 ll.** in the unr
7ea0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 ead portions of
7eb0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 the buffer with
7ec0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 zeros. A VFS th
7ed0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a at.** fails to z
7ee0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
7ef0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 eads might seem
7f00: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 to work. Howeve
7f10: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f r,.** failure to
7f20: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 zero-fill short
7f30: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e reads will even
7f40: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a tually lead to.*
7f50: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 * database corru
7f60: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ption..*/.typede
7f70: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
7f80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 _io_methods sqli
7f90: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a te3_io_methods;.
7fa0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
7fb0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e o_methods {. in
7fc0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
7fd0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 t (*xClose)(sqli
7fe0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
7ff0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 t (*xRead)(sqlit
8000: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c e3_file*, void*,
8010: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
8020: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
8030: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 . int (*xWrite)
8040: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8050: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
8060: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
8070: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
8080: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 nt (*xTruncate)(
8090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
80a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a qlite3_int64 siz
80b0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e e);. int (*xSyn
80c0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a c)(sqlite3_file*
80d0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
80e0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 int (*xFileSize)
80f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8100: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 sqlite3_int64 *p
8110: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Size);. int (*x
8120: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
8130: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 le*, int);. int
8140: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 (*xUnlock)(sqli
8150: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b te3_file*, int);
8160: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 . int (*xCheckR
8170: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c eservedLock)(sql
8180: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
8190: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
81a0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 (*xFileControl)
81b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
81c0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 int op, void *pA
81d0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 rg);. int (*xSe
81e0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 ctorSize)(sqlite
81f0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
8200: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 (*xDeviceCharact
8210: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 eristics)(sqlite
8220: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 3_file*);. /* M
8230: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8240: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
8250: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 1 */. int (*
8260: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 xShmMap)(sqlite3
8270: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c _file*, int iPg,
8280: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 int pgsz, int,
8290: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 void volatile**)
82a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f ;. int (*xShmLo
82b0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
82c0: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 *, int offset, i
82d0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 nt n, int flags)
82e0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 ;. void (*xShmB
82f0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f arrier)(sqlite3_
8300: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8310: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 xShmUnmap)(sqlit
8320: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 e3_file*, int de
8330: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 leteFlag);. /*
8340: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 Methods above ar
8350: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 e valid for vers
8360: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 ion 2 */. /* Ad
8370: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 ditional methods
8380: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
8390: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
83a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
83b0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 PI3REF: Standard
83c0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 File Control Op
83d0: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 codes.**.** Thes
83e0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
83f0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 nts are opcodes
8400: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e for the xFileCon
8410: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f trol method.** o
8420: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
8430: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
8440: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 t and for the [s
8450: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
8460: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 rol()].** interf
8470: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b ace..**.** The [
8480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
8490: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 KSTATE] opcode i
84a0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 s used for debug
84b0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f ging. This.** o
84c0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 pcode causes the
84d0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
84e0: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 thod to write th
84f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 e current state
8500: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 of.** the lock (
8510: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c one of [SQLITE_L
8520: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 OCK_NONE], [SQLI
8530: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
8540: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b .** [SQLITE_LOCK
8550: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c _RESERVED], [SQL
8560: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
8570: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f ], or [SQLITE_LO
8580: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a CK_EXCLUSIVE]).*
8590: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 * into an intege
85a0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 r that the pArg
85b0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 argument points
85c0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c to. This capabil
85d0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 ity.** is used d
85e0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e uring testing an
85f0: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 d only needs to
8600: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 be supported whe
8610: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a n SQLITE_TEST.**
8620: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 is defined..**
8630: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 <ul>.** <li>[[SQ
8640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
8650: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 HINT]].** The [S
8660: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 QLITE_FCNTL_SIZE
8670: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 _HINT] opcode is
8680: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 used by SQLite
8690: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a to give the VFS.
86a0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 ** layer a hint
86b0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 of how large the
86c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
86d0: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 ill grow to be d
86e0: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 uring the.** cur
86f0: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e rent transaction
8700: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 . This hint is
8710: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 not guaranteed t
8720: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 o be accurate bu
8730: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e t it.** is often
8740: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 close. The und
8750: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 erlying VFS migh
8760: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 t choose to prea
8770: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 llocate database
8780: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 .** file space b
8790: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e ased on this hin
87a0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 t in order to he
87b0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 lp writes to the
87c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c database.** fil
87d0: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a e run faster..**
87e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
87f0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a _FCNTL_CHUNK_SIZ
8800: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
8810: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
8820: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 IZE] opcode is u
8830: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 sed to request t
8840: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 hat the VFS.** e
8850: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 xtends and trunc
8860: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ates the databas
8870: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 e file in chunks
8880: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 of a size speci
8890: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 fied.** by the u
88a0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 ser. The fourth
88b0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c argument to [sql
88c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
88d0: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 l()] should .**
88e0: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 point to an inte
88f0: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 ger (type int) c
8900: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 ontaining the ne
8910: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 w chunk-size to
8920: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e use.** for the n
8930: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 ominated databas
8940: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 e. Allocating da
8950: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 tabase file spac
8960: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 e in large.** ch
8970: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 unks (say 1MB at
8980: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 a time), may re
8990: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d duce file-system
89a0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 fragmentation a
89b0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 nd.** improve pe
89c0: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d rformance on som
89d0: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a e systems..**.**
89e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
89f0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
8a00: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
8a10: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
8a20: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 NTER] opcode is
8a30: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 used to obtain a
8a40: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 pointer.** to t
8a50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
8a60: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 ] object associa
8a70: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 ted with a parti
8a80: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a cular database.*
8a90: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 * connection. S
8aa0: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ee the [sqlite3_
8ab0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
8ac0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
8ad0: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 r.** additional
8ae0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
8af0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
8b00: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 FCNTL_SYNC_OMITT
8b10: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 ED]].** ^(The [S
8b20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
8b30: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 _OMITTED] opcode
8b40: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e is generated in
8b50: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 ternally by.** S
8b60: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 QLite and sent t
8b70: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 o all VFSes in p
8b80: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 lace of a call t
8b90: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 o the xSync meth
8ba0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 od.** when the d
8bb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
8bc0: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 on has [PRAGMA s
8bd0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 ynchronous] set
8be0: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d to OFF.)^.** Som
8bf0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 e specialized VF
8c00: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 Ses need this si
8c10: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f gnal in order to
8c20: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 operate correct
8c30: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 ly.** when [PRAG
8c40: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c MA synchronous |
8c50: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e PRAGMA synchron
8c60: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c ous=OFF] is set,
8c70: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 but most .** VF
8c80: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 Ses do not need
8c90: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 this signal and
8ca0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 should silently
8cb0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f ignore this opco
8cc0: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 de..** Applicati
8cd0: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 ons should not c
8ce0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c all [sqlite3_fil
8cf0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 e_control()] wit
8d00: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 h this.** opcode
8d10: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 as doing so may
8d20: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 disrupt the ope
8d30: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 ration of the sp
8d40: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a ecialized VFSes.
8d50: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 ** that do requi
8d60: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c re it. .**.** <
8d70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
8d80: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 L_WIN32_AV_RETRY
8d90: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
8da0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 TE_FCNTL_WIN32_A
8db0: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 V_RETRY] opcode
8dc0: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 is used to confi
8dd0: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a gure automatic.*
8de0: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 * retry counts a
8df0: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 nd intervals for
8e00: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f certain disk I/
8e10: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 O operations for
8e20: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 the.** windows
8e30: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 [VFS] in order t
8e40: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 o provide robust
8e50: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 ness in the pres
8e60: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d ence of.** anti-
8e70: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 virus programs.
8e80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 By default, the
8e90: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c windows VFS wil
8ea0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 l retry file rea
8eb0: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 d,.** file write
8ec0: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 , and file delet
8ed0: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 e operations up
8ee0: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 to 10 times, wit
8ef0: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 h a delay.** of
8f00: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
8f10: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 before the first
8f20: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 retry and with
8f30: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 the delay increa
8f40: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 sing.** by an ad
8f50: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c ditional 25 mill
8f60: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 iseconds with ea
8f70: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 ch subsequent re
8f80: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 try. This.** op
8f90: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 code allows thes
8fa0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 e two values (10
8fb0: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 retries and 25
8fc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
8fd0: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 delay).** to be
8fe0: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 adjusted. The v
8ff0: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 alues are change
9000: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 d for all databa
9010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a se connections.*
9020: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d * within the sam
9030: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 e process. The
9040: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
9050: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 inter to an arra
9060: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 y of two.** inte
9070: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 gers where the f
9080: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 irst integer i t
9090: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 he new retry cou
90a0: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nt and the secon
90b0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 d.** integer is
90c0: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 the delay. If e
90d0: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 ither integer is
90e0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
90f0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 the setting.** i
9100: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 s not changed bu
9110: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 t instead the pr
9120: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 ior value of tha
9130: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 t setting is wri
9140: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 tten.** into the
9150: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c array entry, al
9160: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 lowing the curre
9170: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 nt retry setting
9180: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 s to be.** inter
9190: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 rogated. The zD
91a0: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 bName parameter
91b0: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a is ignored..**.*
91c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
91d0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
91e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
91f0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 TE_FCNTL_PERSIST
9200: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 _WAL] opcode is
9210: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 used to set or q
9220: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 uery the.** pers
9230: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 istent [WAL | Wr
9240: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 ite Ahead Log] s
9250: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 etting. By defa
9260: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 ult, the auxilia
9270: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 ry.** write ahea
9280: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 d log and shared
9290: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 memory files us
92a0: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 ed for transacti
92b0: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 on control.** ar
92c0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
92d0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 deleted when the
92e0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 latest connecti
92f0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 on to the databa
9300: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 se.** closes. S
9310: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e etting persisten
9320: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 t WAL mode cause
9330: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f s those files to
9340: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a persist after.*
9350: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 * close. Persis
9360: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 ting the files i
9370: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 s useful when ot
9380: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 her processes th
9390: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 at do not.** hav
93a0: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 e write permissi
93b0: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 on on the direct
93c0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ory containing t
93d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
93e0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 want.** to read
93f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
9400: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 le, as the WAL a
9410: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 nd shared memory
9420: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 files must exis
9430: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f t.** in order fo
9440: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 r the database t
9450: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 o be readable.
9460: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
9470: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 eter to.** [sqli
9480: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
9490: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 ()] for this opc
94a0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ode should be a
94b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
94c0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 teger..** That i
94d0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 nteger is 0 to d
94e0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e isable persisten
94f0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 t WAL mode or 1
9500: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 to enable persis
9510: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 tent.** WAL mode
9520: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 . If the intege
9530: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 r is -1, then it
9540: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
9550: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
9560: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 .** WAL persiste
9570: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a nce setting..**.
9580: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
9590: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f FCNTL_POWERSAFE_
95a0: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e OVERWRITE]].** ^
95b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
95c0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
95d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 WRITE] opcode is
95e0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 used to set or
95f0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 query the.** per
9600: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 sistent "powersa
9610: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 fe-overwrite" or
9620: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e "PSOW" setting.
9630: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 The PSOW setti
9640: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 ng.** determines
9650: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 the [SQLITE_IOC
9660: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
9670: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 RWRITE] bit of t
9680: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 he.** xDeviceCha
9690: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 racteristics met
96a0: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 hods. The fourth
96b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
96c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
96d0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 ontrol()] for th
96e0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 is opcode should
96f0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
9700: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 an integer..**
9710: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 That integer is
9720: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 0 to disable zer
9730: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 o-damage mode or
9740: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 1 to enable zer
9750: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 o-damage.** mode
9760: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 . If the intege
9770: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 r is -1, then it
9780: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
9790: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
97a0: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 .** zero-damage
97b0: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a mode setting..**
97c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
97d0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
97e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
97f0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 TE_FCNTL_OVERWRI
9800: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e TE] opcode is in
9810: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 voked by SQLite
9820: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a after opening.**
9830: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 a write transac
9840: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 tion to indicate
9850: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 that, unless it
9860: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 is rolled back
9870: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 for some.** reas
9880: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 on, the entire d
9890: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c atabase file wil
98a0: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e l be overwritten
98b0: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 by the current
98c0: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e .** transaction.
98d0: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 This is used by
98e0: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f VACUUM operatio
98f0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ns..**.** <li>[[
9900: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
9910: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b NAME]].** ^The [
9920: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
9930: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e NAME] opcode can
9940: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 be used to obta
9950: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a in the names of.
9960: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 ** all [VFSes] i
9970: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e n the VFS stack.
9980: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 The names are
9990: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 of all VFS shims
99a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 and the.** fina
99b0: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 l bottom-level V
99c0: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 FS are written i
99d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
99e0: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 ned from .** [sq
99f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
9a00: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 and the result i
9a10: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 s stored in the
9a20: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a char* variable.*
9a30: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 * that the fourt
9a40: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b h parameter of [
9a50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
9a60: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 trol()] points t
9a70: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 o..** The caller
9a80: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
9a90: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 for freeing the
9aa0: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 memory when done
9ab0: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c . As with.** al
9ac0: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 l file-control a
9ad0: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 ctions, there is
9ae0: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 no guarantee th
9af0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 at this will act
9b00: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 ually.** do anyt
9b10: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 hing. Callers s
9b20: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 hould initialize
9b30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 the char* varia
9b40: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a ble to a NULL.**
9b50: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 pointer in case
9b60: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 this file-contr
9b70: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d ol is not implem
9b80: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c ented. This fil
9b90: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 e-control.** is
9ba0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 intended for dia
9bb0: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 gnostic use only
9bc0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
9bd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
9be0: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 A]].** ^Whenever
9bf0: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 a [PRAGMA] stat
9c00: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c ement is parsed,
9c10: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 an [SQLITE_FCNT
9c20: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 L_PRAGMA] .** fi
9c30: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 le control is se
9c40: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b nt to the open [
9c50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
9c60: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 ject correspondi
9c70: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 ng.** to the dat
9c80: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 abase file to wh
9c90: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 ich the pragma s
9ca0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e tatement refers.
9cb0: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a ^The argument.*
9cc0: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 * to the [SQLITE
9cd0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 _FCNTL_PRAGMA] f
9ce0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 ile control is a
9cf0: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f n array of.** po
9d00: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
9d10: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 s (char**) in wh
9d20: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 ich the second e
9d30: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 lement of the ar
9d40: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ray.** is the na
9d50: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 me of the pragma
9d60: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 and the third e
9d70: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 lement is the ar
9d80: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
9d90: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 pragma or NULL
9da0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 if the pragma ha
9db0: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 s no argument.
9dc0: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 ^The handler for
9dd0: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 an.** [SQLITE_F
9de0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
9df0: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 e control can op
9e00: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 tionally make th
9e10: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a e first element.
9e20: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a ** of the char**
9e30: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 argument point
9e40: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 to a string obta
9e50: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
9e60: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a e3_mprintf()].**
9e70: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 or the equivale
9e80: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 nt and that stri
9e90: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 ng will become t
9ea0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 he result of the
9eb0: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 pragma or.** th
9ec0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
9ed0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 if the pragma fa
9ee0: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 ils. ^If the.**
9ef0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
9f00: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
9f10: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ol returns [SQLI
9f20: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 TE_NOTFOUND], th
9f30: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 en normal .** [P
9f40: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e RAGMA] processin
9f50: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 g continues. ^I
9f60: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 f the [SQLITE_FC
9f70: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 NTL_PRAGMA].** f
9f80: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 ile control retu
9f90: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c rns [SQLITE_OK],
9fa0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 then the parser
9fb0: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
9fc0: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e e.** VFS has han
9fd0: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 dled the PRAGMA
9fe0: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 itself and the p
9ff0: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 arser generates
a000: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 a no-op.** prepa
a010: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 red statement.
a020: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
a030: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 FCNTL_PRAGMA] fi
a040: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 le control retur
a050: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 ns.** any result
a060: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e code other than
a070: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
a080: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 [SQLITE_NOTFOUND
a090: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a ], that means.**
a0a0: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e that the VFS en
a0b0: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 countered an err
a0c0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e or while handlin
a0d0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 g the [PRAGMA] a
a0e0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c nd the.** compil
a0f0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 ation of the PRA
a100: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 GMA fails with a
a110: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b n error. ^The [
a120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
a130: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e GMA].** file con
a140: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 trol occurs at t
a150: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
a160: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 pragma statement
a170: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f analysis and so
a180: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 .** it is able t
a190: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 o override built
a1a0: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 -in [PRAGMA] sta
a1b0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c tements..** </ul
a1c0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
a1d0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
a1e0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ATE
a1f0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
a200: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_GET_LOCKPROXY
a210: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 FILE
a220: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
a230: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 E_SET_LOCKPROXYF
a240: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ILE
a250: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
a260: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
a270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 4
a280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a290: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 FCNTL_SIZE_HINT
a2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
a2b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
a2c0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 CNTL_CHUNK_SIZE
a2d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 6.#
a2e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
a2f0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
a300: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 7.#d
a310: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
a320: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 TL_SYNC_OMITTED
a330: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 8.#de
a340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
a350: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 L_WIN32_AV_RETRY
a360: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
a370: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
a380: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 _PERSIST_WAL
a390: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 10.#defi
a3a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
a3b0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 OVERWRITE
a3c0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 11.#defin
a3d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 e SQLITE_FCNTL_V
a3e0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 FSNAME
a3f0: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 12.#define
a400: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f SQLITE_FCNTL_PO
a410: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
a420: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 E 13.#define
a430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
a440: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 GMA
a450: 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 14../*.** CA
a460: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 PI3REF: Mutex Ha
a470: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d ndle.**.** The m
a480: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 utex module with
a490: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 in SQLite define
a4a0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 s [sqlite3_mutex
a4b0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 ] to be an.** ab
a4c0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 stract type for
a4d0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 a mutex object.
a4e0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
a4f0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 never looks.**
a500: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 at the internal
a510: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f representation o
a520: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 f an [sqlite3_mu
a530: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a tex]. It only.*
a540: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 * deals with poi
a550: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 nters to the [sq
a560: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a lite3_mutex] obj
a570: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 ect..**.** Mutex
a580: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 es are created u
a590: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 sing [sqlite3_mu
a5a0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f tex_alloc()]..*/
a5b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
a5c0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 sqlite3_mutex sq
a5d0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a lite3_mutex;../*
a5e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
a5f0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 Interface Objec
a600: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 t.**.** An insta
a610: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 nce of the sqlit
a620: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 e3_vfs object de
a630: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
a640: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 ace between.** t
a650: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 he SQLite core a
a660: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
a670: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 g operating syst
a680: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a em. The "vfs".*
a690: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 * in the name of
a6a0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e the object stan
a6b0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 ds for "virtual
a6c0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 file system". S
a6d0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c ee.** the [VFS |
a6e0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 VFS documentati
a6f0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 on] for further
a700: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
a710: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 ** The value of
a720: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
a730: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 ld is initially
a740: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 1 but may be lar
a750: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 ger in.** future
a760: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
a770: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ite. Additional
a780: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
a790: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a ppended to this.
a7a0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 ** object when t
a7b0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 he iVersion valu
a7c0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 e is increased.
a7d0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 Note that the s
a7e0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 tructure.** of t
a7f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
a800: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e bject changes in
a810: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
a820: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 between.** SQLi
a830: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 te version 3.5.9
a840: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 and 3.6.0 and y
a850: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 et the iVersion
a860: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a field was not.**
a870: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a modified..**.**
a880: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 The szOsFile fi
a890: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 eld is the size
a8a0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 of the subclasse
a8b0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d d [sqlite3_file]
a8c0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 .** structure us
a8d0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 ed by this VFS.
a8e0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 mxPathname is t
a8f0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
a900: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 h of.** a pathna
a910: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a me in this VFS..
a920: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 **.** Registered
a930: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a sqlite3_vfs obj
a940: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e ects are kept on
a950: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 a linked list f
a960: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 ormed by.** the
a970: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 pNext pointer.
a980: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
a990: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 _register()].**
a9a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 and [sqlite3_vfs
a9b0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 _unregister()] i
a9c0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 nterfaces manage
a9d0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e this list.** in
a9e0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 a thread-safe w
a9f0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ay. The [sqlite
aa00: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 3_vfs_find()] in
aa10: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 terface.** searc
aa20: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e hes the list. N
aa30: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 either the appli
aa40: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 cation code nor
aa50: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 the VFS.** imple
aa60: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
aa70: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 use the pNext p
aa80: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
aa90: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 e pNext field is
aaa0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 the only field
aab0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
aac0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 fs.** structure
aad0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
aae0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 ever modify. S
aaf0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 QLite will only
ab00: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 access.** or mod
ab10: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 ify this field w
ab20: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 hile holding a p
ab30: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 articular static
ab40: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 mutex..** The a
ab50: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
ab60: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 d never modify a
ab70: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 nything within t
ab80: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
ab90: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 * object once th
aba0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 e object has bee
abb0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a n registered..**
abc0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 .** The zName fi
abd0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 eld holds the na
abe0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f me of the VFS mo
abf0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 dule. The name
ac00: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 must.** be uniqu
ac10: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 e across all VFS
ac20: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 modules..**.**
ac30: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [[sqlite3_vfs.xO
ac40: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 pen]].** ^SQLite
ac50: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
ac60: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
ac70: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
ac80: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 n.** is either a
ac90: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 NULL pointer or
aca0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
acb0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 .** from xFullPa
acc0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e thname() with an
acd0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 optional suffix
ace0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 added..** ^If a
acf0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 suffix is added
ad00: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d to the zFilenam
ad10: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 e parameter, it
ad20: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 will.** consist
ad30: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 of a single "-"
ad40: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 character follow
ad50: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 ed by no more th
ad60: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 an.** 11 alphanu
ad70: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 meric and/or "-"
ad80: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 characters..**
ad90: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 ^SQLite further
ada0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a guarantees that.
adb0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 ** the string wi
adc0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 ll be valid and
add0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 unchanged until
ade0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 xClose() is.** c
adf0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f alled. Because o
ae00: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 f the previous s
ae10: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 entence,.** the
ae20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 [sqlite3_file] c
ae30: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 an safely store
ae40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
ae50: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 .** filename if
ae60: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 it needs to reme
ae70: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d mber the filenam
ae80: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f e for some reaso
ae90: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 n..** If the zFi
aea0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
aeb0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e to xOpen is a N
aec0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
aed0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 xOpen.** must i
aee0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 nvent its own te
aef0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 mporary name for
af00: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 the file. ^Whe
af10: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 never the .** xF
af20: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
af30: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c r is NULL it wil
af40: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 l also be the ca
af50: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 se that the.** f
af60: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 lags parameter w
af70: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c ill include [SQL
af80: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
af90: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 NCLOSE]..**.** T
afa0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
afb0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 t to xOpen() inc
afc0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 ludes all bits s
afd0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 et in.** the fla
afe0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b gs argument to [
aff0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
b000: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 )]. Or if [sqli
b010: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f te3_open()].** o
b020: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 r [sqlite3_open1
b030: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 6()] is used, th
b040: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 en flags include
b050: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 s at least.** [S
b060: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
b070: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
b080: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a OPEN_CREATE]. .*
b090: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 * If xOpen() ope
b0a0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f ns a file read-o
b0b0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 nly then it sets
b0c0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a *pOutFlags to.*
b0d0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 * include [SQLIT
b0e0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
b0f0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e . Other bits in
b100: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 *pOutFlags may
b110: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 be set..**.** ^(
b120: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f SQLite will also
b130: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
b140: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
b150: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a to the xOpen().*
b160: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e * call, dependin
b170: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 g on the object
b180: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a being opened:.**
b190: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
b1a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
b1b0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 AIN_DB].** <li>
b1c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
b1d0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c IN_JOURNAL].** <
b1e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
b1f0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c N_TEMP_DB].** <l
b200: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
b210: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _TEMP_JOURNAL].*
b220: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
b230: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
b240: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
b250: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
b260: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
b270: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
b280: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c R_JOURNAL].** <l
b290: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
b2a0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e _WAL].** </ul>)^
b2b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 .**.** The file
b2c0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 I/O implementati
b2d0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f on can use the o
b2e0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 bject type flags
b2f0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 to.** change th
b300: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 e way it deals w
b310: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 ith files. For
b320: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
b330: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 ication.** that
b340: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 does not care ab
b350: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 out crash recove
b360: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d ry or rollback m
b370: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 ight make.** the
b380: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e open of a journ
b390: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e al file a no-op.
b3a0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 Writes to this
b3b0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a journal would.*
b3c0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 * also be no-ops
b3d0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 , and any attemp
b3e0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f t to read the jo
b3f0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 urnal would retu
b400: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 rn.** SQLITE_IOE
b410: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c RR. Or the impl
b420: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 ementation might
b430: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 recognize that
b440: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 a database.** fi
b450: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 le will be doing
b460: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 page-aligned se
b470: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 ctor reads and w
b480: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f rites in a rando
b490: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 m.** order and s
b4a0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 et up its I/O su
b4b0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e bsystem accordin
b4c0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 gly..**.** SQLit
b4d0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 e might also add
b4e0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
b4f0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
b500: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a he xOpen method:
b510: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
b520: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e li> [SQLITE_OPEN
b530: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
b540: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
b550: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a OPEN_EXCLUSIVE].
b560: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
b570: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
b580: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 DELETEONCLOSE] f
b590: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
b5a0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 le should be.**
b5b0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 deleted when it
b5c0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 is closed. ^The
b5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
b5e0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
b5f0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 will be set for
b600: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 TEMP databases a
b610: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c nd their journal
b620: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 s, transient.**
b630: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 databases, and s
b640: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a ubjournals..**.*
b650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f * ^The [SQLITE_O
b660: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 PEN_EXCLUSIVE] f
b670: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 lag is always us
b680: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f ed in conjunctio
b690: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 n.** with the [S
b6a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
b6b0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 E] flag, which a
b6c0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 re both directly
b6d0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f .** analogous to
b6e0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 the O_EXCL and
b6f0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 O_CREAT flags of
b700: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 the POSIX open(
b710: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 ).** API. The S
b720: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
b730: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 SIVE flag, when
b740: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 paired with the
b750: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f .** SQLITE_OPEN_
b760: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 CREATE, is used
b770: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
b780: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 file should alw
b790: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 ays.** be create
b7a0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 d, and that it i
b7b0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 s an error if it
b7c0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e already exists.
b7d0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 .** It is <i>not
b7e0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 </i> used to ind
b7f0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 icate the file s
b800: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 hould be opened
b810: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 .** for exclusiv
b820: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 e access..**.**
b830: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 ^At least szOsFi
b840: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f le bytes of memo
b850: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 ry are allocated
b860: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f by SQLite.** to
b870: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 hold the [sqli
b880: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 te3_file] struct
b890: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 ure passed as th
b8a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d e third.** argum
b8b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 ent to xOpen. T
b8c0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
b8d0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f does not have to
b8e0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 .** allocate the
b8f0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 structure; it s
b900: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 hould just fill
b910: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 it in. Note tha
b920: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d t.** the xOpen m
b930: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 ethod must set t
b940: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
b950: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 pMethods to eith
b960: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 er.** a valid [s
b970: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
b980: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 s] object or to
b990: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 NULL. xOpen mus
b9a0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 t do.** this eve
b9b0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 n if the open fa
b9c0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 ils. SQLite exp
b9d0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 ects that the sq
b9e0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
b9f0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 ods.** element w
ba00: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 ill be valid aft
ba10: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 er xOpen returns
ba20: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
ba30: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 he success.** or
ba40: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 failure of the
ba50: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a xOpen call..**.*
ba60: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
ba70: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 xAccess]].** ^Th
ba80: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
ba90: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 to xAccess() ma
baa0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 y be [SQLITE_ACC
bab0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 ESS_EXISTS].** t
bac0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 o test for the e
bad0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 xistence of a fi
bae0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
baf0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d CCESS_READWRITE]
bb00: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 to.** test whet
bb10: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 her a file is re
bb20: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
bb30: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ble, or [SQLITE_
bb40: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 ACCESS_READ].**
bb50: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 to test whether
bb60: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 a file is at lea
bb70: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 st readable. T
bb80: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 he file can be a
bb90: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a .** directory..*
bba0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c *.** ^SQLite wil
bbb0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 l always allocat
bbc0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 e at least mxPat
bbd0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f hname+1 bytes fo
bbe0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 r the.** output
bbf0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 buffer xFullPath
bc00: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 name. The exact
bc10: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 size of the out
bc20: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
bc30: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 also passed as
bc40: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 a parameter to b
bc50: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 oth methods. If
bc60: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
bc70: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 er.** is not lar
bc80: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 ge enough, [SQLI
bc90: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f TE_CANTOPEN] sho
bca0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
bcb0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a Since this is.*
bcc0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 * handled as a f
bcd0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 atal error by SQ
bce0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d Lite, vfs implem
bcf0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
bd00: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 endeavor.** to
bd10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 prevent this by
bd20: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 setting mxPathna
bd30: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 me to a sufficie
bd40: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 ntly large value
bd50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e ..**.** The xRan
bd60: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 domness(), xSlee
bd70: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d p(), xCurrentTim
bd80: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e e(), and xCurren
bd90: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 tTimeInt64().**
bda0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e interfaces are n
bdb0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 ot strictly a pa
bdc0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 rt of the filesy
bdd0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 stem, but they a
bde0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 re.** included i
bdf0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 n the VFS struct
be00: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 ure for complete
be10: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 ness..** The xRa
be20: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 ndomness() funct
be30: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ion attempts to
be40: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 return nBytes by
be50: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 tes.** of good-q
be60: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 uality randomnes
be70: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 s into zOut. Th
be80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 e return value i
be90: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 s.** the actual
bea0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
beb0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 of randomness ob
bec0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 tained..** The x
bed0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 Sleep() method c
bee0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e auses the callin
bef0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 g thread to slee
bf00: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 p for at.** leas
bf10: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
bf20: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 microseconds giv
bf30: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 en. ^The xCurre
bf40: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 ntTime().** meth
bf50: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c od returns a Jul
bf60: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 ian Day Number f
bf70: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 or the current d
bf80: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a ate and time as.
bf90: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f ** a floating po
bfa0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 int value..** ^T
bfb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
bfc0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 nt64() method re
bfd0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 turns, as an int
bfe0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e eger, the Julian
bff0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d .** Day Number m
c000: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 ultiplied by 864
c010: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 00000 (the numbe
c020: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
c030: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f s in .** a 24-ho
c040: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 ur day). .** ^S
c050: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
c060: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
c070: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f nt64() method to
c080: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 get the current
c090: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d .** date and tim
c0a0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 e if that method
c0b0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 is available (i
c0c0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 f iVersion is 2
c0d0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 or .** greater a
c0e0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 nd the function
c0f0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
c100: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 ULL) and will fa
c110: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 ll back.** to xC
c120: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 urrentTime() if
c130: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
c140: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 4() is unavailab
c150: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 le..**.** ^The x
c160: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c SetSystemCall(),
c170: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xGetSystemCall(
c180: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 ), and xNestSyst
c190: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 emCall() interfa
c1a0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 ces.** are not u
c1b0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 sed by the SQLit
c1c0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f e core. These o
c1d0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 ptional interfac
c1e0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a es are provided.
c1f0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 ** by some VFSes
c200: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 to facilitate t
c210: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 esting of the VF
c220: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 S code. By overr
c230: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d iding .** system
c240: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 calls with func
c250: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 tions under its
c260: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 control, a test
c270: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 program can.** s
c280: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 imulate faults a
c290: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 nd error conditi
c2a0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f ons that would o
c2b0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 therwise be diff
c2c0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f icult.** or impo
c2d0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 ssible to induce
c2e0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 . The set of sy
c2f0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 stem calls that
c300: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
c310: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d n.** varies from
c320: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 one VFS to anot
c330: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e her, and from on
c340: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 e version of the
c350: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 same VFS to the
c360: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 .** next. Appli
c370: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 cations that use
c380: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
c390: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 s must be prepar
c3a0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 ed for any.** or
c3b0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e all of these in
c3c0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e terfaces to be N
c3d0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 ULL or for their
c3e0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 behavior to cha
c3f0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 nge.** from one
c400: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e release to the n
c410: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
c420: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 ns must not atte
c430: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a mpt to access.**
c440: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 any of these me
c450: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 thods if the iVe
c460: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 rsion of the VFS
c470: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e is less than 3.
c480: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
c490: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 ct sqlite3_vfs s
c4a0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 qlite3_vfs;.type
c4b0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
c4c0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 e3_syscall_ptr)(
c4d0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 void);.struct sq
c4e0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e lite3_vfs {. in
c4f0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 t iVersion;
c500: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 /* Struct
c510: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 ure version numb
c520: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 er (currently 3)
c530: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 */. int szOsFi
c540: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f le; /
c550: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 * Size of subcla
c560: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c ssed sqlite3_fil
c570: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 e */. int mxPat
c580: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 hname;
c590: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 /* Maximum file
c5a0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 pathname length
c5b0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 */. sqlite3_vfs
c5c0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a *pNext; /*
c5d0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 Next registered
c5e0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 VFS */. const
c5f0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 char *zName;
c600: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
c610: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 is virtual file
c620: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 system */. void
c630: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
c640: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 /* Pointer
c650: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 to application-s
c660: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a pecific data */.
c670: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
c680: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
c690: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
c6a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 sqlite3_file*,.
c6b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
c6c0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f t flags, int *pO
c6d0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 utFlags);. int
c6e0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 (*xDelete)(sqlit
c6f0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
c700: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
c710: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 syncDir);. int
c720: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 (*xAccess)(sqlit
c730: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
c740: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
c750: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 flags, int *pRes
c760: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
c770: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c ullPathname)(sql
c780: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
c790: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
c7a0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f t nOut, char *zO
c7b0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ut);. void *(*x
c7c0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f DlOpen)(sqlite3_
c7d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
c7e0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 *zFilename);.
c7f0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 void (*xDlError)
c800: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
c810: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
c820: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 zErrMsg);. void
c830: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c (*(*xDlSym)(sql
c840: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c ite3_vfs*,void*,
c850: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 const char *zSy
c860: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 mbol))(void);.
c870: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 void (*xDlClose)
c880: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 (sqlite3_vfs*, v
c890: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 oid*);. int (*x
c8a0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 Randomness)(sqli
c8b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
c8c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 yte, char *zOut)
c8d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 ;. int (*xSleep
c8e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
c8f0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 int microseconds
c900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 );. int (*xCurr
c910: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 entTime)(sqlite3
c920: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b _vfs*, double*);
c930: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 . int (*xGetLas
c940: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f tError)(sqlite3_
c950: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 vfs*, int, char
c960: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 *);. /*. ** Th
c970: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
c980: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 are in version 1
c990: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
c9a0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 fs object. ** d
c9b0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 efinition. Thos
c9c0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 e that follow ar
c9d0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 e added in versi
c9e0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 on 2 or later.
c9f0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 */. int (*xCurr
ca00: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 entTimeInt64)(sq
ca10: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 lite3_vfs*, sqli
ca20: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f te3_int64*);. /
ca30: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
ca40: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
ca50: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 versions 1 and 2
ca60: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
ca70: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 fs object.. **
ca80: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 Those below are
ca90: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e for version 3 an
caa0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a d greater.. */.
cab0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 int (*xSetSyst
cac0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
cad0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
cae0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
caf0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 _syscall_ptr);.
cb00: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
cb10: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 _ptr (*xGetSyste
cb20: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
cb30: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
cb40: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 *zName);. const
cb50: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 char *(*xNextSy
cb60: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
cb70: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
cb80: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a ar *zName);. /*
cb90: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
cba0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
cbb0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 ersions 1 throug
cbc0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 h 3 of the sqlit
cbd0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 e_vfs object..
cbe0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 ** New fields ma
cbf0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
cc00: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 figure versions
cc10: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
cc20: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
cc30: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
cc40: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
cc50: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a . */.};../*.**
cc60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
cc70: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 for the xAccess
cc80: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
cc90: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
cca0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 constants can be
ccb0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 used as the thi
ccc0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a rd parameter to.
ccd0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ** the xAccess m
cce0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c ethod of an [sql
ccf0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
cd00: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e . They determin
cd10: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f e.** what kind o
cd20: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 f permissions th
cd30: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
cd40: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e is looking for.
cd50: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
cd60: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 ACCESS_EXISTS, t
cd70: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
cd80: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 d.** simply chec
cd90: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
cda0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 ile exists..** W
cdb0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
cdc0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 S_READWRITE, the
cdd0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
cde0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
cdf0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 r the named dire
ce00: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 ctory is both re
ce10: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
ce20: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 ble.** (in other
ce30: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 words, if files
ce40: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 can be added, r
ce50: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 emoved, and rena
ce60: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 med within.** th
ce70: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a e directory)..**
ce80: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
ce90: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e SS_READWRITE con
cea0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 stant is current
ceb0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 ly used only by
cec0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f the.** [temp_sto
ced0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
cee0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 gma], though thi
cef0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 s could change i
cf00: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 n a future.** re
cf10: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
cf20: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
cf30: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 ACCESS_READ, the
cf40: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
cf50: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
cf60: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 r the file is re
cf70: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c adable. The SQL
cf80: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
cf90: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 constant is.** c
cfa0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c urrently unused,
cfb0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 though it might
cfc0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 be used in a fu
cfd0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a ture release of.
cfe0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 ** SQLite..*/.#d
cff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
d000: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a ESS_EXISTS 0.
d010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
d020: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
d030: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 1 /* Used by P
d040: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 RAGMA temp_store
d050: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 _directory */.#d
d060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
d070: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 ESS_READ 2
d080: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a /* Unused */..
d090: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
d0a0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 Flags for the xS
d0b0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f hmLock VFS metho
d0c0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
d0d0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
d0e0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f define the vario
d0f0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 us locking opera
d100: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 tions.** allowed
d110: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b by the xShmLock
d120: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 method of [sqli
d130: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e te3_io_methods].
d140: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 The.** followi
d150: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 ng are the only
d160: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f legal combinatio
d170: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 ns of flags to t
d180: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d he.** xShmLock m
d190: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
d1a0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 >.** <li> SQLIT
d1b0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c E_SHM_LOCK | SQL
d1c0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
d1d0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
d1e0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 HM_LOCK | SQLITE
d1f0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
d200: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
d210: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
d220: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
d230: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
d240: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
d250: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
d260: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 ** </ul>.**.** W
d270: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 hen unlocking, t
d280: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f he same SHARED o
d290: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 r EXCLUSIVE flag
d2a0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 must be supplie
d2b0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 d as.** was give
d2c0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 n no the corresp
d2d0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a onding lock. .*
d2e0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
d2f0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 k method can tra
d300: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
d310: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 unlocked and SHA
d320: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 RED or.** betwee
d330: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 n unlocked and E
d340: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 XCLUSIVE. It ca
d350: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 nnot transition
d360: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a between SHARED.*
d370: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e * and EXCLUSIVE.
d380: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
d390: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 TE_SHM_UNLOCK
d3a0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
d3b0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 LITE_SHM_LOCK
d3c0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
d3d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
d3e0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e D 4.#defin
d3f0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 e SQLITE_SHM_EXC
d400: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a LUSIVE 8../*.
d410: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 ** CAPI3REF: Max
d420: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e imum xShmLock in
d430: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 dex.**.** The xS
d440: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e hmLock method on
d450: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
d460: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 hods] may use va
d470: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
d480: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 0 and this upper
d490: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f bound as its "o
d4a0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e ffset" argument.
d4b0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
d4c0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 ore will never a
d4d0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 ttempt to acquir
d4e0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a e or release a.*
d4f0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f * lock outside o
d500: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a f this range.*/.
d510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
d520: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 HM_NLOCK
d530: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8.../*.** CAPI3R
d540: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 EF: Initialize T
d550: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
d560: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c y.**.** ^The sql
d570: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
d580: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 ) routine initia
d590: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c lizes the.** SQL
d5a0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 ite library. ^T
d5b0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
d5c0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a own() routine.**
d5d0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 deallocates any
d5e0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 resources that
d5f0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 were allocated b
d600: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 y sqlite3_initia
d610: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 lize()..** These
d620: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 routines are de
d630: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e signed to aid in
d640: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c process initial
d650: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 ization and.** s
d660: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 hutdown on embed
d670: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f ded systems. Wo
d680: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 rkstation applic
d690: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 ations using.**
d6a0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 SQLite normally
d6b0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 do not need to i
d6c0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 nvoke either of
d6d0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
d6e0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
d6f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
d700: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 ze() is an "effe
d710: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
d720: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 t is.** the firs
d730: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
d740: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
d750: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 nvoked during th
d760: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a e lifetime of.**
d770: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 the process, or
d780: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
d790: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
d7a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
d7b0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c invoked.** foll
d7c0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 owing a call to
d7d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d7e0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 (). ^(Only an e
d7f0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a ffective call.**
d800: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 of sqlite3_init
d810: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e ialize() does an
d820: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
d830: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c . All other cal
d840: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 ls.** are harmle
d850: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a ss no-ops.)^.**.
d860: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
d870: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
d880: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
d890: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 " call if it is
d8a0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c the first.** cal
d8b0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
d8c0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 tdown() since th
d8d0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 e last sqlite3_i
d8e0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 nitialize(). ^(
d8f0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 Only.** an effec
d900: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c tive call to sql
d910: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
d920: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 does any deiniti
d930: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c alization..** Al
d940: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 l other valid ca
d950: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 lls to sqlite3_s
d960: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 hutdown() are ha
d970: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e rmless no-ops.)^
d980: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
d990: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
d9a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 interface is thr
d9b0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c eadsafe, but sql
d9c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
d9d0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 ** is not. The
d9e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d9f0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 () interface mus
da00: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 t only be called
da10: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c from a.** singl
da20: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f e thread. All o
da30: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
da40: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 nnections] must
da50: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c be closed and al
da60: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 l.** other SQLit
da70: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 e resources must
da80: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
da90: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e prior to invokin
daa0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 g.** sqlite3_shu
dab0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 tdown()..**.** A
dac0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
dad0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 s, ^sqlite3_init
dae0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e ialize() will in
daf0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
db00: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
db10: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f larly, ^sqlite3_
db20: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 shutdown().** wi
db30: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
db40: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
db50: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
db60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
db70: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
db80: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
db90: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 ss..** ^If for s
dba0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 ome reason, sqli
dbb0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
dbc0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e is unable to in
dbd0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 itialize.** the
dbe0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 library (perhaps
dbf0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
dc00: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 allocate a need
dc10: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 ed resource such
dc20: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 .** as a mutex)
dc30: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 it returns an [e
dc40: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 rror code] other
dc50: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
dc60: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
dc70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
dc80: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 () routine is ca
dc90: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 lled internally
dca0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by many other.**
dcb0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
dcc0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 es so that an ap
dcd0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c plication usuall
dce0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 y does not need
dcf0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c to.** invoke sql
dd00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
dd10: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 ) directly. For
dd20: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 example, [sqlit
dd30: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 e3_open()].** ca
dd40: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 lls sqlite3_init
dd50: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 ialize() so the
dd60: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
dd70: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
dd80: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ally.** initiali
dd90: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 zed when [sqlite
dda0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 3_open()] is cal
ddb0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f led if it has no
ddc0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 t be initialized
ddd0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 .** already. ^H
dde0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 owever, if SQLit
ddf0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
de00: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
de10: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a MIT_AUTOINIT].**
de20: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
de30: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 tion, then the a
de40: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 utomatic calls t
de50: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
de60: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d lize().** are om
de70: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 itted and the ap
de80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 plication must c
de90: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 all sqlite3_init
dea0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
deb0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 y.** prior to us
dec0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
ded0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
dee0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 For maximum por
def0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 tability,.** it
df00: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
df10: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
df20: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 always invoke s
df30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
df40: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 e().** directly
df50: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
df60: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
df70: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 interface. Futu
df80: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f re releases.** o
df90: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 f SQLite may req
dfa0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f uire this. In o
dfb0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
dfc0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 behavior exhibit
dfd0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 ed.** when SQLit
dfe0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
dff0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f th [SQLITE_OMIT_
e000: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 AUTOINIT] might
e010: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 become the.** de
e020: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
e030: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
e040: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
e050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
e060: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 e3_os_init() rou
e070: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 tine does operat
e080: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
e090: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a fic.** initializ
e0a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c ation of the SQL
e0b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
e0c0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
e0d0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e ().** routine un
e0e0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 does the effect
e0f0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
e100: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 it(). Typical t
e110: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 asks.** performe
e120: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 d by these routi
e130: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f nes include allo
e140: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f cation or deallo
e150: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 cation.** of sta
e160: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 tic resources, i
e170: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
e180: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 global variable
e190: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 s,.** setting up
e1a0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 a default [sqli
e1b0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c te3_vfs] module,
e1c0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a or setting up.*
e1d0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 * a default conf
e1e0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 iguration using
e1f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
e200: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 )]..**.** The ap
e210: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
e220: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 never invoke ei
e230: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ther sqlite3_os_
e240: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c init().** or sql
e250: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 ite3_os_end() di
e260: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 rectly. The app
e270: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
e280: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 only invoke.** s
e290: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
e2a0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
e2b0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 shutdown(). The
e2c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
e2d0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
e2e0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 is called automa
e2f0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
e300: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
e310: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f and.** sqlite3_o
e320: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 s_end() is calle
e330: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 d by sqlite3_shu
e340: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 tdown(). Approp
e350: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 riate.** impleme
e360: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c ntations for sql
e370: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
e380: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
e390: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 d().** are built
e3a0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 into SQLite whe
e3b0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 n it is compiled
e3c0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f for Unix, Windo
e3d0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 ws, or OS/2..**
e3e0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 When [custom bui
e3f0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 lds | built for
e400: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d other platforms]
e410: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b .** (using the [
e420: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d SQLITE_OS_OTHER=
e430: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 1] compile-time.
e440: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 ** option) the a
e450: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
e460: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c supply a suitabl
e470: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
e480: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
e490: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
e4a0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 lite3_os_end().
e4b0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
e4c0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c supplied.** impl
e4d0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
e4e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
e4f0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
e500: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 d().** must retu
e510: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
e520: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f n success and so
e530: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 me other [error
e540: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 code] upon.** fa
e550: 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ilure..*/.SQLITE
e560: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
e570: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
e580: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
e590: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f t sqlite3_shutdo
e5a0: 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 wn(void);.SQLITE
e5b0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
e5c0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a _os_init(void);.
e5d0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
e5e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f qlite3_os_end(vo
e5f0: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 id);../*.** CAPI
e600: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 3REF: Configurin
e610: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 g The SQLite Lib
e620: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 rary.**.** The s
e630: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
e640: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
e650: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c d to make global
e660: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
e670: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c * changes to SQL
e680: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
e690: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 tune SQLite to t
e6a0: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 he specific need
e6b0: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c s of.** the appl
e6c0: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 ication. The de
e6d0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
e6e0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ion is recommend
e6f0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 ed for most.** a
e700: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 pplications and
e710: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 so this routine
e720: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e is usually not n
e730: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 ecessary. It is
e740: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 .** provided to
e750: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 support rare app
e760: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 lications with u
e770: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a nusual needs..**
e780: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
e790: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
e7a0: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 ce is not thread
e7b0: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 safe. The appli
e7c0: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 cation.** must i
e7d0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 nsure that no ot
e7e0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
e7f0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 faces are invoke
e800: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 d by other.** th
e810: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 reads while sqli
e820: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
e830: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 running. Furthe
e840: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 rmore, sqlite3_c
e850: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f onfig().** may o
e860: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 nly be invoked p
e870: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 rior to library
e880: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 initialization u
e890: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
e8a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f _initialize()] o
e8b0: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e r after shutdown
e8c0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 by [sqlite3_shu
e8d0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 tdown()]..** ^If
e8e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
e8f0: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 ) is called afte
e900: 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 r [sqlite3_initi
e910: 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 alize()] and bef
e920: 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
e930: 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e shutdown()] then
e940: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 it will return
e950: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a SQLITE_MISUSE..*
e960: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c * Note, however,
e970: 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 that ^sqlite3_c
e980: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 onfig() can be c
e990: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 alled as part of
e9a0: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
e9b0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 tation of an app
e9c0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
e9d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 [sqlite3_os_ini
e9e0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t()]..**.** The
e9f0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
ea00: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 o sqlite3_config
ea10: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 () is an integer
ea20: 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 .** [configurati
ea30: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 on option] that
ea40: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 determines.** wh
ea50: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 at property of S
ea60: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 QLite is to be c
ea70: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 onfigured. Subs
ea80: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 equent arguments
ea90: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 .** vary dependi
eaa0: 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 ng on the [confi
eab0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
eac0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
ead0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
eae0: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 ^When a configu
eaf0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
eb00: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f set, sqlite3_co
eb10: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b nfig() returns [
eb20: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e SQLITE_OK]..** ^
eb30: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 If the option is
eb40: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 unknown or SQLi
eb50: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
eb60: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a set the option.*
eb70: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 * then this rout
eb80: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ine returns a no
eb90: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
eba0: 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 de]..*/.SQLITE_A
ebb0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
ebc0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b onfig(int, ...);
ebd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
ebe0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 : Configure data
ebf0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
ec00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
ec10: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
ec20: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
ec30: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 to make configu
ec40: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
ec50: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 s to a [database
ec60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
ec70: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 he interface is
ec80: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 similar to.** [s
ec90: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
eca0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
ecb0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 changes apply t
ecc0: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 o a single.** [d
ecd0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ece0: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 on] (specified i
ecf0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
ed00: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment)..**.** The
ed10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
ed20: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
ed30: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 onfig(D,V,...)
ed40: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 is the.** [SQLIT
ed50: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
ed60: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 SIDE | configura
ed70: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 tion verb] - an
ed80: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a integer code .**
ed90: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
eda0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 what aspect of t
edb0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
edc0: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
edd0: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
ede0: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
edf0: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e ments vary depen
ee00: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 ding on the conf
ee10: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a iguration verb..
ee20: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 **.** ^Calls to
ee30: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
ee40: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 g() return SQLIT
ee50: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 E_OK if and only
ee60: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 if.** the call
ee70: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 is considered su
ee80: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c ccessful..*/.SQL
ee90: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
eea0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 te3_db_config(sq
eeb0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 lite3*, int op,
eec0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
eed0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
eee0: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 location Routine
eef0: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 s.**.** An insta
ef00: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
ef10: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
ef20: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
ef30: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c SQLite.** and l
ef40: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 ow-level memory
ef50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
ef60: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 nes..**.** This
ef70: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 object is used i
ef80: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 n only one place
ef90: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 in the SQLite i
efa0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 nterface..** A p
efb0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
efc0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
efd0: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 ject is the argu
efe0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ment to.** [sqli
eff0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 te3_config()] wh
f000: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 en the configura
f010: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a tion option is.*
f020: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
f030: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c _MALLOC] or [SQL
f040: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
f050: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 LLOC]. .** By c
f060: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 reating an insta
f070: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
f080: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e ct.** and passin
f090: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
f0a0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 _config]([SQLITE
f0b0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 _CONFIG_MALLOC])
f0c0: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 .** during confi
f0d0: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 guration, an app
f0e0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 lication can spe
f0f0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 cify an alternat
f100: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ive.** memory al
f110: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
f120: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f em for SQLite to
f130: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 use for all of
f140: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d its.** dynamic m
f150: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a emory needs..**.
f160: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c ** Note that SQL
f170: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 ite comes with s
f180: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e everal [built-in
f190: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
f1a0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 rs].** that are
f1b0: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 perfectly adequa
f1c0: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 te for the overw
f1d0: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 helming majority
f1e0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 of applications
f1f0: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 .** and that thi
f200: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 s object is only
f210: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e useful to a tin
f220: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 y minority of ap
f230: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 plications.** wi
f240: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d th specialized m
f250: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
f260: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 requirements.
f270: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a This object is.*
f280: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 * also used duri
f290: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 ng testing of SQ
f2a0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f Lite in order to
f2b0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 specify an alte
f2c0: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 rnative.** memor
f2d0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 y allocator that
f2e0: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 simulates memor
f2f0: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 y out-of-memory
f300: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a conditions in.**
f310: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 order to verify
f320: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 that SQLite rec
f330: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 overs gracefully
f340: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f from such.** co
f350: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 nditions..**.**
f360: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 The xMalloc, xRe
f370: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 alloc, and xFree
f380: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f methods must wo
f390: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d rk like the.** m
f3a0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 alloc(), realloc
f3b0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 () and free() fu
f3c0: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 nctions from the
f3d0: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
f3e0: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ary..** ^SQLite
f3f0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
f400: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
f410: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c ent to.** xReall
f420: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 oc is always a v
f430: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
f440: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f a prior call to
f450: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a xRoundup..**.**
f460: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 xSize should re
f470: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 turn the allocat
f480: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d ed size of a mem
f490: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
f4a0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 * previously obt
f4b0: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c ained from xMall
f4c0: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 oc or xRealloc.
f4d0: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 The allocated s
f4e0: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 ize.** is always
f4f0: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 at least as big
f500: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 as the requeste
f510: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 d size but may b
f520: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 e larger..**.**
f530: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 The xRoundup met
f540: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 hod returns what
f550: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c would be the al
f560: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a located size of.
f570: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ** a memory allo
f580: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 cation given a p
f590: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 articular reques
f5a0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 ted size. Most
f5b0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
f5c0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 tors round up me
f5d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
f5e0: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 at least to the
f5f0: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a next multiple.*
f600: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c * of 8. Some al
f610: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
f620: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 p to a larger mu
f630: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 ltiple or to a p
f640: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 ower of 2..** Ev
f650: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ery memory alloc
f660: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f ation request co
f670: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 ming in through
f680: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
f690: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
f6a0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 3_realloc()] fir
f6b0: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 st calls xRoundu
f6c0: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 p. If xRoundup
f6d0: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 returns 0, .** t
f6e0: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 hat causes the c
f6f0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d orresponding mem
f700: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
f710: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 o fail..**.** Th
f720: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 e xInit method i
f730: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d nitializes the m
f740: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e emory allocator.
f750: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a (For example,.
f760: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f ** it might allo
f770: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 cate any require
f780: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 mutexes or init
f790: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 ialize internal
f7a0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 data.** structur
f7b0: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f es. The xShutdo
f7c0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 wn method is inv
f7d0: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 oked (indirectly
f7e0: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ) by.** [sqlite3
f7f0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 _shutdown()] and
f800: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 should dealloca
f810: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 te any resources
f820: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 acquired.** by
f830: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 xInit. The pApp
f840: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 Data pointer is
f850: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 used as the only
f860: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
f870: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 xInit and xShut
f880: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 down..**.** SQLi
f890: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 te holds the [SQ
f8a0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
f8b0: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 C_MASTER] mutex
f8c0: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a when it invokes.
f8d0: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 ** the xInit met
f8e0: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 hod, so the xIni
f8f0: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f t method need no
f900: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
f910: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f The.** xShutdo
f920: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c wn method is onl
f930: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 y called from [s
f940: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f950: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a )] so it does.**
f960: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
f970: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 threadsafe eithe
f980: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 r. For all othe
f990: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 r methods, SQLit
f9a0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b e.** holds the [
f9b0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
f9c0: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 TIC_MEM] mutex a
f9d0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a s long as the.**
f9e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
f9f0: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 MEMSTATUS] confi
fa00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
fa10: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 is turned on (wh
fa20: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 ich.** it is by
fa30: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 default) and so
fa40: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 the methods are
fa50: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 automatically se
fa60: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 rialized..** How
fa70: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 ever, if [SQLITE
fa80: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
fa90: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 S] is disabled,
faa0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a then the other.*
fab0: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 * methods must b
fac0: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 e threadsafe or
fad0: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 else make their
fae0: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 own arrangements
faf0: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a for.** serializ
fb00: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ation..**.** SQL
fb10: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 ite will never i
fb20: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f nvoke xInit() mo
fb30: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 re than once wit
fb40: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e hout an interven
fb50: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 ing.** call to x
fb60: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 Shutdown()..*/.t
fb70: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
fb80: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
fb90: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 s sqlite3_mem_me
fba0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
fbb0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
fbc0: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d s {. void *(*xM
fbd0: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 alloc)(int);
fbe0: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 /* Memory a
fbf0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 llocation functi
fc00: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 on */. void (*x
fc10: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Free)(void*);
fc20: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 /* Free a
fc30: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
fc40: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 n */. void *(*x
fc50: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 Realloc)(void*,i
fc60: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 nt); /* Resize
fc70: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f an allocation */
fc80: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 . int (*xSize)(
fc90: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
fca0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 /* Return the
fcb0: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 size of an alloc
fcc0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 ation */. int (
fcd0: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b *xRoundup)(int);
fce0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 /* Rou
fcf0: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 nd up request si
fd00: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e ze to allocation
fd10: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 size */. int (
fd20: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 *xInit)(void*);
fd30: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 /* Ini
fd40: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
fd50: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
fd60: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f void (*xShutdo
fd70: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 wn)(void*);
fd80: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 /* Deinitialize
fd90: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
fda0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
fdb0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
fdc0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
fdd0: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 ument to xInit()
fde0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 and xShutdown()
fdf0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
fe00: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
fe10: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
fe20: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 KEYWORDS: {conf
fe30: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
fe40: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
fe50: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
fe60: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
fe70: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
fe80: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
fe90: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
fea0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
feb0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
fec0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
fed0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
fee0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
fef0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
ff00: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
ff10: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
ff20: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
ff30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
ff40: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
ff50: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
ff60: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
ff70: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
ff80: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
ff90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
ffa0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
ffb0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
ffc0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 worked. The [s
ffd0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
ffe0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
fff0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
10000 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
10010 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
10020 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
10030 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
10040 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
10050 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
10060 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f >.** [[SQLITE_CO
10070 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
10080 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
10090 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
100a0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
100b0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
100c0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
100d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 tion. ^This opt
100e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
100f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
10100 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 to Single-threa
10110 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 d. In other wor
10120 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a ds, it disables.
10130 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 ** all mutexing
10140 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 and puts SQLite
10150 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 into a mode wher
10160 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 e it can only be
10170 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 used.** by a si
10180 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e ngle thread. ^
10190 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
101a0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
101b0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
101c0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
101d0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
101e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
101f0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
10200 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 t possible to ch
10210 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 ange the [thread
10220 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 ing mode] from i
10230 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 ts default.** va
10240 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 lue of Single-th
10250 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c read and so [sql
10260 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
10270 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b ill return .** [
10280 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
10290 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
102a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
102b0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 INGLETHREAD.** c
102c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
102d0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
102e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
102f0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 MULTITHREAD]] <d
10300 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
10310 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e MULTITHREAD</dt>
10320 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
10330 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
10340 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
10350 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
10360 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
10370 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c ing mode] to Mul
10380 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f ti-thread. In o
10390 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 ther words, it d
103a0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 isables.** mutex
103b0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 ing on [database
103c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
103d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
103e0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
103f0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
10400 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 n is responsible
10410 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 for serializing
10420 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 access to.** [d
10430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10440 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
10450 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 ed statements].
10460 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 But other mutex
10470 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 es.** are enable
10480 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 d so that SQLite
10490 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f will be safe to
104a0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d use in a multi-
104b0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 threaded.** envi
104c0 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 ronment as long
104d0 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 as no two thread
104e0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 s attempt to use
104f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 the same.** [da
10500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10510 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 n] at the same t
10520 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 ime. ^If SQLite
10530 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
10540 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
10550 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
10560 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
10570 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
10580 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
10590 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
105a0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c e to set the Mul
105b0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
105c0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
105d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
105e0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
105f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
10600 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
10610 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
10620 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
10630 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
10640 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
10650 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
10660 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 _SERIALIZED]] <d
10670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
10680 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a SERIALIZED</dt>.
10690 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
106a0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
106b0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e this option. ^
106c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
106d0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 the.** [threadi
106e0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 ng mode] to Seri
106f0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 alized. In other
10700 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 words, this opt
10710 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 ion enables.** a
10720 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 ll mutexes inclu
10730 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 ding the recursi
10740 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e ve.** mutexes on
10750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
10760 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
10770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
10780 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 objects..** In t
10790 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 his mode (which
107a0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 is the default w
107b0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
107c0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b mpiled with.** [
107d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
107e0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 E=1]) the SQLite
107f0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 library will it
10800 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 self serialize a
10810 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 ccess.** to [dat
10820 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
10830 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
10840 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 statements] so
10850 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c that the.** appl
10860 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 ication is free
10870 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 to use the same
10880 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10890 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 tion] or the.**
108a0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
108b0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 tatement] in dif
108c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 ferent threads a
108d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
108e0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 .** ^If SQLite i
108f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
10900 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
10910 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
10920 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
10930 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
10940 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
10950 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
10960 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 to set the Seria
10970 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
10980 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
10990 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
109a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
109b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
109c0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
109d0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
109e0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 SERIALIZED confi
109f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
10a00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
10a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
10a20 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OC]] <dt>SQLITE_
10a30 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 CONFIG_MALLOC</d
10a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
10a50 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
10a60 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
10a70 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
10a80 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 ter to an.** ins
10a90 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
10aa0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
10ab0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
10ac0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
10ad0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
10ae0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
10af0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
10b00 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
10b10 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 used in place of
10b20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 .** the memory a
10b30 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
10b40 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 es built into SQ
10b50 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 Lite.)^ ^SQLite
10b60 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e makes.** its own
10b70 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
10b80 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
10b90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
10ba0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
10bb0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 ure.** before th
10bc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
10bd0 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e g()] call return
10be0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b s.</dd>.**.** [[
10bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
10c00 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 TMALLOC]] <dt>SQ
10c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
10c20 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
10c30 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
10c40 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
10c50 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
10c60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
10c70 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
10c80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
10c90 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
10ca0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 ture. The [sqli
10cb0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
10cc0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
10cd0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
10ce0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
10cf0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
10d00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e tion routines.)^
10d10 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
10d20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
10d30 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
10d40 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
10d50 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
10d60 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
10d70 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e that simulation
10d80 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
10d90 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a ion failure or.*
10da0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 * tracks memory
10db0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 usage, for examp
10dc0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 le. </dd>.**.**
10dd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
10de0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e MEMSTATUS]] <dt>
10df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
10e00 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 MSTATUS</dt>.**
10e10 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
10e20 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 n takes single a
10e30 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
10e40 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 int, interpreted
10e50 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 as a .** boolea
10e60 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 n, which enables
10e70 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
10e80 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d collection of m
10e90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
10ea0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e .** statistics.
10eb0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 ^(When memory a
10ec0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
10ed0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 tics are disable
10ee0 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f d, the .** follo
10ef0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 wing SQLite inte
10f00 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f rfaces become no
10f10 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a n-operational:.*
10f20 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c * <ul>.** <l
10f30 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
10f40 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 ry_used()].**
10f50 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
10f60 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
10f70 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
10f80 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
10f90 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c imit64()].** <
10fa0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 li> [sqlite3_sta
10fb0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c tus()].** </ul
10fc0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 >)^.** ^Memory a
10fd0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
10fe0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 tics are enabled
10ff0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 by default unle
11000 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 ss SQLite is.**
11010 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
11020 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 QLITE_DEFAULT_ME
11030 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 MSTATUS]=0 in wh
11040 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a ich case memory.
11050 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ** allocation st
11060 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 atistics are dis
11070 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
11080 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
11090 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
110a0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 _SCRATCH]] <dt>S
110b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
110c0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATCH</dt>.** <dd
110d0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 > ^This option s
110e0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
110f0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
11100 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
11110 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 use for.** scrat
11120 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 ch memory. Ther
11130 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
11140 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 ments: A pointe
11150 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 r an 8-byte.** a
11160 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 ligned memory bu
11170 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 ffer from which
11180 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f the scratch allo
11190 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a cations will be.
111a0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 ** drawn, the si
111b0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 ze of each scrat
111c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 ch allocation (s
111d0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d z),.** and the m
111e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
111f0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
11200 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 ions (N). The s
11210 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 z.** argument mu
11220 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 st be a multiple
11230 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 of 16..** The f
11240 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
11250 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 st be a pointer
11260 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 to an 8-byte ali
11270 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f gned buffer.** o
11280 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
11290 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
112a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
112b0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 use no more tha
112c0 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 n two scratch bu
112d0 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 ffers per thread
112e0 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c . So.** N shoul
112f0 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 d be set to twic
11300 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d e the expected m
11310 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
11320 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 threads..** ^SQ
11330 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
11340 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 require a scratc
11350 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 h buffer that is
11360 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 more than 6.**
11370 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 times the databa
11380 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 se page size. ^I
11390 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e f SQLite needs n
113a0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a eeds additional.
113b0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 ** scratch memor
113c0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 y beyond what is
113d0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
113e0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
113f0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a option, then .**
11400 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
11410 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 ()] will be used
11420 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d to obtain the m
11430 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 emory needed.</d
11440 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
11450 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
11460 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f HE]] <dt>SQLITE_
11470 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
11480 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
11490 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
114a0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
114b0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
114c0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
114d0 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 for.** the datab
114e0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
114f0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
11500 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
11510 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 mentation. .**
11520 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 This configurati
11530 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 on should not be
11540 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c used if an appl
11550 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 ication-define p
11560 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 age.** cache imp
11570 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c lementation is l
11580 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 oaded using the
11590 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
115a0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a ACHE2 option..**
115b0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 There are three
115c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
115d0 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 is option: A poi
115e0 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 nter to 8-byte a
115f0 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 ligned.** memory
11600 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 , the size of ea
11610 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 ch page buffer (
11620 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d sz), and the num
11630 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 ber of pages (N)
11640 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 ..** The sz argu
11650 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 ment should be t
11660 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c he size of the l
11670 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 argest database
11680 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 page.** (a power
11690 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 of two between
116a0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 512 and 32768) p
116b0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 lus a little ext
116c0 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 ra for each.** p
116d0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 age header. ^Th
116e0 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 e page header si
116f0 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 ze is 20 to 40 b
11700 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f ytes depending o
11710 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 n.** the host ar
11720 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 chitecture. ^It
11730 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 is harmless, ap
11740 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 art from the was
11750 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 ted memory,.** t
11760 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 o make sz a litt
11770 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 le too large. T
11780 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 he first.** argu
11790 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e ment should poin
117a0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 t to an allocati
117b0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 on of at least s
117c0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d z*N bytes of mem
117d0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ory..** ^SQLite
117e0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d will use the mem
117f0 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 ory provided by
11800 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
11810 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 nt to satisfy it
11820 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 s.** memory need
11830 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 s for the first
11840 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 N pages that it
11850 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 adds to cache.
11860 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a ^If additional.*
11870 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d * page cache mem
11880 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 ory is needed be
11890 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f yond what is pro
118a0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 vided by this op
118b0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 tion, then.** SQ
118c0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 Lite goes to [sq
118d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
118e0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e for the addition
118f0 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 al storage space
11900 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 ..** The pointer
11910 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
11920 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 gument must.** b
11930 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
11940 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 8-byte boundary
11950 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 or subsequent be
11960 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 havior of SQLite
11970 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 .** will be unde
11980 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a fined.</dd>.**.*
11990 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
119a0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c G_HEAP]] <dt>SQL
119b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c ITE_CONFIG_HEAP<
119c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
119d0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 is option specif
119e0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
119f0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 ory buffer that
11a00 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
11a10 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 ** for all of it
11a20 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
11a30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
11a40 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 s beyond those p
11a50 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 rovided.** for b
11a60 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
11a70 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 _SCRATCH] and [S
11a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
11a90 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 ECACHE]..** Ther
11aa0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
11ab0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 ments: An 8-byte
11ac0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 aligned pointer
11ad0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a to the memory,.
11ae0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
11af0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 bytes in the me
11b00 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 mory buffer, and
11b10 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
11b20 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a ocation size..**
11b30 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 ^If the first p
11b40 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
11b50 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e ry pointer) is N
11b60 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ULL, then SQLite
11b70 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 reverts.** to u
11b80 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 sing its default
11b90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
11ba0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 r (the system ma
11bb0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 lloc() implement
11bc0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 ation),.** undoi
11bd0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 ng any prior inv
11be0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 ocation of [SQLI
11bf0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
11c00 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d ]. ^If the.** m
11c10 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 emory pointer is
11c20 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 not NULL and ei
11c30 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 ther [SQLITE_ENA
11c40 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a BLE_MEMSYS3] or.
11c50 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
11c60 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 E_MEMSYS5] are d
11c70 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 efined, then the
11c80 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
11c90 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
11ca0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 is engaged to h
11cb0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c andle all of SQL
11cc0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ites memory allo
11cd0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a cation needs..**
11ce0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 The first point
11cf0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
11d00 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 ointer) must be
11d10 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
11d20 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 byte.** boundary
11d30 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
11d40 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
11d50 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 e will be undefi
11d60 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 ned..** The mini
11d70 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
11d80 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 ize is capped at
11d90 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 2**12. Reasonab
11da0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
11db0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
11dc0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
11dd0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2**5 through 2*
11de0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b *8.</dd>.**.** [
11df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
11e00 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
11e10 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f E_CONFIG_MUTEX</
11e20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
11e30 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
11e40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
11e50 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
11e60 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
11e70 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
11e80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
11e90 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
11ea0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 The argument s
11eb0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
11ec0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
11ed0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 l mutex routines
11ee0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
11ef0 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 lace.** the mute
11f00 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 x routines built
11f10 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 into SQLite.)^
11f20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^SQLite makes a
11f30 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
11f40 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b content of the [
11f50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
11f60 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
11f70 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c before the call
11f80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
11f90 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e config()] return
11fa0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 s. ^If SQLite is
11fb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
11fc0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
11fd0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
11fe0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
11ff0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
12000 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ion then.** the
12010 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 entire mutexing
12020 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 subsystem is omi
12030 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 tted from the bu
12040 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 ild and hence ca
12050 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
12060 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 e3_config()] wit
12070 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
12080 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 FIG_MUTEX config
12090 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 uration option w
120a0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
120b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 QLITE_ERROR].</d
120c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
120d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
120e0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 X]] <dt>SQLITE_C
120f0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f ONFIG_GETMUTEX</
12100 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
12110 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
12120 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
12130 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
12140 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
12150 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
12160 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
12170 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
12180 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 The.** [sqlite
12190 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
121a0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
121b0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
121c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
121d0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 ed mutex routine
121e0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 s.)^.** This opt
121f0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
12200 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
12210 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c default mutex al
12220 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
12230 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
12240 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 per used to trac
12250 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f k mutex usage fo
12260 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a r performance.**
12270 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 profiling or te
12280 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 sting, for examp
12290 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 le. ^If SQLite
122a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
122b0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
122c0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
122d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
122e0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
122f0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
12300 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
12310 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
12320 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
12330 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
12340 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
12350 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
12360 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
12370 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
12380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
12390 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
123a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
123b0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b R].</dd>.**.** [
123c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
123d0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 OOKASIDE]] <dt>S
123e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
123f0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
12400 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
12410 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 n takes two argu
12420 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
12430 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 mine the default
12440 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
12450 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f ation for the lo
12460 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
12470 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 llocator on each
12480 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
12490 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
124a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
124b0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
124c0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
124d0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 buffer slot and
124e0 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 the second is th
124f0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
12500 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 lots allocated t
12510 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
12520 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e connection.)^ ^
12530 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 (This option set
12540 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 s the.** <i>defa
12550 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 ult</i> lookasid
12560 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c e size. The [SQL
12570 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
12580 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 KASIDE].** verb
12590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
125a0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 onfig()] can be
125b0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
125c0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 he lookaside.**
125d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e configuration on
125e0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e individual conn
125f0 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e ections.)^ </dd>
12600 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
12610 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d CONFIG_PCACHE2]]
12620 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
12630 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a IG_PCACHE2</dt>.
12640 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
12650 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
12660 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
12670 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
12680 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 to.** an [sqlit
12690 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
126a0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 s2] object. Thi
126b0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 s object specifi
126c0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
126d0 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 .** to a custom
126e0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
126f0 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 mentation.)^ ^S
12700 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
12710 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a py of the.** obj
12720 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 ect and uses it
12730 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d for page cache m
12740 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12750 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b s.</dd>.**.** [[
12760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
12770 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 TPCACHE2]] <dt>S
12780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
12790 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 PCACHE2</dt>.**
127a0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
127b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
127c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
127d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
127e0 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
127f0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
12800 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 object. SQLite
12810 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 copies of the c
12820 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 urrent.** page c
12830 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
12840 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 ion into that ob
12850 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ject.)^ </dd>.**
12860 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
12870 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 FIG_LOG]] <dt>SQ
12880 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c LITE_CONFIG_LOG<
12890 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
128a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
128b0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOG option takes
128c0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 two arguments:
128d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a a pointer to a.*
128e0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 * function with
128f0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 a call signature
12900 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 of void(*)(void
12910 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
12920 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f *), .** and a po
12930 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e inter to void. ^
12940 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 If the function
12950 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
12960 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e ULL, it is.** in
12970 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 voked by [sqlite
12980 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 3_log()] to proc
12990 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 ess each logging
129a0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 event. ^If the
129b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 .** function poi
129c0 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 nter is NULL, th
129d0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 e [sqlite3_log()
129e0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f ] interface beco
129f0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 mes a no-op..**
12a00 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 ^The void pointe
12a10 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 r that is the se
12a20 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
12a30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
12a40 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 OG is.** passed
12a50 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 through as the f
12a60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
12a70 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
12a80 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 n-defined logger
12a90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 .** function whe
12aa0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 never that funct
12ab0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ion is invoked.
12ac0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
12ad0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
12ae0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e logger function
12af0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
12b00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
12b10 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 r to the corresp
12b20 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 onding.** [sqlit
12b30 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 e3_log()] call a
12b40 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 nd is intended t
12b50 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 o be a [result c
12b60 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 ode] or an.** [e
12b70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
12b80 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 ode]. ^The thir
12b90 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 d parameter pass
12ba0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 ed to the logger
12bb0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 is.** log messa
12bc0 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 ge after formatt
12bd0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 ing via [sqlite3
12be0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a _snprintf()]..**
12bf0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 The SQLite logg
12c00 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 ing interface is
12c10 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 not reentrant;
12c20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
12c30 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 ion.** supplied
12c40 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
12c50 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f on must not invo
12c60 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e ke any SQLite in
12c70 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 terface..** In a
12c80 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 multi-threaded
12c90 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 application, the
12ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
12cb0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 ined logger.** f
12cc0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 unction must be
12cd0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 threadsafe. </dd
12ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12cf0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 _CONFIG_URI]] <d
12d00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12d10 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 URI.** <dd> This
12d20 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
12d30 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
12d40 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 of type int. If
12d50 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a non-zero, then.*
12d60 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 * URI handling i
12d70 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c s globally enabl
12d80 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d ed. If the param
12d90 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 eter is zero, th
12da0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a en URI handling.
12db0 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 ** is globally d
12dc0 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 isabled. If URI
12dd0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
12de0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c ally enabled, al
12df0 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 l filenames.** p
12e00 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 assed to [sqlite
12e10 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
12e20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
12e30 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
12e40 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 )] or.** specifi
12e50 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 ed as part of [A
12e60 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 TTACH] commands
12e70 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 are interpreted
12e80 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c as URIs, regardl
12e90 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 ess.** of whethe
12ea0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 r or not the [SQ
12eb0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
12ec0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 lag is set when
12ed0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
12ee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 connection is op
12ef0 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 ened. If it is g
12f00 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 lobally disabled
12f10 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a , filenames are.
12f20 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 ** only interpre
12f30 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 ted as URIs if t
12f40 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 he SQLITE_OPEN_U
12f50 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 RI flag is set w
12f60 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 hen the.** datab
12f70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
12f80 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 s opened. By def
12f90 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 ault, URI handli
12fa0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a ng is globally.*
12fb0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 * disabled. The
12fc0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 default value ma
12fd0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 y be changed by
12fe0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 compiling with t
12ff0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 he.** [SQLITE_US
13000 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 E_URI] symbol de
13010 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 fined..**.** [[S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
13030 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 CHE]] [[SQLITE_C
13040 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d ONFIG_GETPCACHE]
13050 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
13060 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e CONFIG_PCACHE an
13070 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f d SQLITE_CONFIG_
13080 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 GETPCACHE.** <dd
13090 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 > These options
130a0 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 are obsolete and
130b0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 should not be u
130c0 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e sed by new code.
130d0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 .** They are ret
130e0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 ained for backwa
130f0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
13100 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f y but are now no
13110 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a -ops..** </dl>.*
13120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
13130 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
13140 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 READ 1 /* nil
13150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
13160 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
13170 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c READ 2 /* nil
13180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
13190 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
131a0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 IZED 3 /* ni
131b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
131c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
131d0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 C 4 /* s
131e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
131f0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
13200 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
13210 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a MALLOC 5 /*
13220 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
13230 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
13240 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
13250 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 CRATCH 6
13260 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
13270 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
13280 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
13290 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 _PAGECACHE 7
132a0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
132b0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
132c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
132d0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 IG_HEAP
132e0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 8 /* void*, in
132f0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e t nByte, int min
13300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
13310 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
13320 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f TUS 9 /* bo
13330 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 olean */.#define
13340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
13350 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 UTEX 10
13360 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
13370 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
13380 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
13390 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 IG_GETMUTEX
133a0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 11 /* sqlite3_m
133b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
133c0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 ./* previously S
133d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 QLITE_CONFIG_CHU
133e0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 NKALLOC 12 which
133f0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 is now unused.
13400 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */ .#define SQLI
13410 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
13420 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e IDE 13 /* in
13430 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 t int */.#define
13440 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
13450 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 CACHE 14
13460 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
13470 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
13480 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 G_GETPCACHE 1
13490 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 5 /* no-op */.#
134a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
134b0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 NFIG_LOG
134c0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 16 /* xFunc,
134d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
134e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 SQLITE_CONFIG_U
134f0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 RI 17
13500 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e /* int */.#defin
13510 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13520 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 PCACHE2 18
13530 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
13540 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
13550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
13560 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
13570 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 19 /* sqlite
13580 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
13590 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 2* */../*.** CAP
135a0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
135b0 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 Connection Confi
135c0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 guration Options
135d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
135e0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 stants are the a
135f0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 vailable integer
13600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13610 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 ptions that.** c
13620 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 an be passed as
13630 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
13640 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
13650 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
13660 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
13670 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
13680 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
13690 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
136a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
136b0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
136c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
136d0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
136e0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
136f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
13700 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
13710 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
13720 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 om [sqlite3_db_c
13730 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 onfig()] to make
13740 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 sure that.** th
13750 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 e call worked.
13760 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 ^The [sqlite3_db
13770 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
13780 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
13790 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
137a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
137b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
137c0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
137d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
137e0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
137f0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c .**.** <dl>.** <
13800 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
13810 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
13820 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
13830 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 option takes thr
13840 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 ee additional ar
13850 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
13860 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b ermine the .** [
13870 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
13880 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 allocator] conf
13890 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 iguration for th
138a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
138b0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 ection]..** ^The
138c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
138d0 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d (the third param
138e0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
138f0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 _db_config()] is
13900 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f a.** pointer to
13910 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 a memory buffer
13920 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b to use for look
13930 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a aside memory..**
13940 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
13950 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 ment after the S
13960 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
13970 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a OOKASIDE verb.**
13980 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 may be NULL in
13990 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 which case SQLit
139a0 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 e will allocate
139b0 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 the.** lookaside
139c0 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 buffer itself u
139d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 sing [sqlite3_ma
139e0 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 lloc()]. ^The se
139f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
13a00 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
13a10 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
13a20 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 uffer slot. ^Th
13a30 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
13a40 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
13a50 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 f.** slots. The
13a60 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
13a70 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 fer in the first
13a80 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
13a90 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a e greater than.*
13aa0 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 * or equal to th
13ab0 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 e product of the
13ac0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 second and thir
13ad0 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 d arguments. Th
13ae0 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 e buffer.** must
13af0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
13b00 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8-byte boundar
13b10 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f y. ^If the seco
13b20 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
13b30 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 * SQLITE_DBCONFI
13b40 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e G_LOOKASIDE is n
13b50 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 ot a multiple of
13b60 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 8, it is intern
13b70 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 ally.** rounded
13b80 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 down to the next
13b90 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c smaller multipl
13ba0 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c e of 8. ^(The l
13bb0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a ookaside memory.
13bc0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
13bd0 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 for a database
13be0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f connection can o
13bf0 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 nly be changed w
13c00 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e hen that.** conn
13c10 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 ection is not cu
13c20 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f rrently using lo
13c30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 okaside memory,
13c40 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 or in other word
13c50 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 s.** when the "c
13c60 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 urrent value" re
13c70 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
13c80 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d lite3_db_status]
13c90 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 (D,[SQLITE_CONFI
13ca0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e G_LOOKASIDE],...
13cb0 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e ) is zero..** An
13cc0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 y attempt to cha
13cd0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 nge the lookasid
13ce0 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 e memory configu
13cf0 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b ration when look
13d00 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 aside.** memory
13d10 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 is in use leaves
13d20 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
13d30 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 on unchanged and
13d40 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 returns .** [SQ
13d50 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 LITE_BUSY].)^</d
13d60 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
13d70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
13d80 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a BLE_FKEY</dt>.**
13d90 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
13da0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
13db0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
13dc0 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 the enforcement
13dd0 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b of.** [foreign k
13de0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e ey constraints].
13df0 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 There should b
13e00 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
13e10 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
13e20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
13e30 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
13e40 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
13e50 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 sable FK enforce
13e60 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 ment,.** positiv
13e70 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 e to enable FK e
13e80 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 nforcement or ne
13e90 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 gative to leave
13ea0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a FK enforcement.*
13eb0 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 * unchanged. Th
13ec0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
13ed0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
13ee0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
13ef0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
13f00 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
13f10 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
13f20 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 r FK enforcement
13f30 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a is off or on.**
13f40 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
13f50 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
13f60 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
13f70 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
13f80 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
13f90 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 ase the FK enfor
13fa0 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 cement setting i
13fb0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
13fc0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
13fd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
13fe0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 NFIG_ENABLE_TRIG
13ff0 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GER</dt>.** <dd>
14000 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 ^This option is
14010 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 used to enable
14020 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 or disable [CREA
14030 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
14040 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 ggers]..** There
14050 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
14060 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
14070 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
14080 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
14090 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
140a0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 s 0 to disable t
140b0 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 riggers,.** posi
140c0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 tive to enable t
140d0 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 riggers or negat
140e0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 ive to leave the
140f0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 setting unchang
14100 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e ed..** The secon
14110 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
14120 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
14130 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
14140 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
14150 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
14160 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 te whether trigg
14170 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 ers are disabled
14180 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 or enabled.** f
14190 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
141a0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
141b0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
141c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
141d0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
141e0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 e the trigger se
141f0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 tting is not rep
14200 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 orted back. </dd
14210 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f >.**.** </dl>.*/
14220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
14230 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
14240 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f DE 1001 /
14250 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
14260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14270 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
14280 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 E_FKEY 1002
14290 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
142a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
142b0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 BCONFIG_ENABLE_T
142c0 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a RIGGER 1003 /*
142d0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f int int* */.../
142e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
142f0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 nable Or Disable
14300 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
14310 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 Codes.**.** ^Th
14320 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
14330 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
14340 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 ) routine enable
14350 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
14360 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 e.** [extended r
14370 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 esult codes] fea
14380 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 ture of SQLite.
14390 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 ^The extended re
143a0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 sult.** codes ar
143b0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 e disabled by de
143c0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 fault for histor
143d0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 ical compatibili
143e0 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ty..*/.SQLITE_AP
143f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 I int sqlite3_ex
14400 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
14410 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
14420 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
14430 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
14440 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a Insert Rowid.**.
14450 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 ** ^Each entry i
14460 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c n an SQLite tabl
14470 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 e has a unique 6
14480 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
14490 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
144a0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
144b0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 "rowid"]. ^The r
144c0 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 owid is always a
144d0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 vailable.** as a
144e0 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c n undeclared col
144f0 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c umn named ROWID,
14500 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f OID, or _ROWID_
14510 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 as long as thos
14520 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e e.** names are n
14530 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 ot also used by
14540 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
14550 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 red columns. ^If
14560 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 .** the table ha
14570 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 s a column of ty
14580 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d pe [INTEGER PRIM
14590 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 ARY KEY] then th
145a0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 at column.** is
145b0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f another alias fo
145c0 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a r the rowid..**.
145d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
145e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f returns the [ro
145f0 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 wid] of the most
14600 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 recent.** succe
14610 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 ssful [INSERT] i
14620 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
14630 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 from the [datab
14640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
14650 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
14660 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f argument. ^As o
14670 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
14680 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 3.7.7, this rou
14690 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 tines.** records
146a0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
146b0 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f rowid of both o
146c0 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 rdinary tables a
146d0 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c nd [virtual tabl
146e0 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 es]..** ^If no s
146f0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
14700 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 T]s.** have ever
14710 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 occurred on tha
14720 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 t database conne
14730 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 ction, zero is r
14740 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
14750 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 (If an [INSERT]
14760 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 occurs within a
14770 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 trigger or withi
14780 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 n a [virtual tab
14790 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 le].** method, t
147a0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
147b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 will return the
147c0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
147d0 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 inserted.** row
147e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
147f0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 rigger or virtua
14800 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 l table method i
14810 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 s running..** Bu
14820 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 t once the trigg
14830 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 er or virtual ta
14840 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c ble method ends,
14850 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
14860 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 ned .** by this
14870 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 routine reverts
14880 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 to what it was b
14890 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 efore the trigge
148a0 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 r or virtual.**
148b0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 table method beg
148c0 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 an.)^.**.** ^An
148d0 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 [INSERT] that fa
148e0 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e ils due to a con
148f0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
14900 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 n is not a.** su
14910 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
14920 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 ] and does not c
14930 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 hange the value
14940 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
14950 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 .** routine. ^T
14960 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 hus INSERT OR FA
14970 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 IL, INSERT OR IG
14980 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 NORE, INSERT OR
14990 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 ROLLBACK,.** and
149a0 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 INSERT OR ABORT
149b0 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 make no changes
149c0 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 to the return v
149d0 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 alue of this.**
149e0 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 routine when the
149f0 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 ir insertion fai
14a00 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 ls. ^(When INSE
14a10 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a RT OR REPLACE.**
14a20 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f encounters a co
14a30 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
14a40 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 on, it does not
14a50 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e fail. The.** IN
14a60 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 SERT continues t
14a70 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 o completion aft
14a80 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 er deleting rows
14a90 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 that caused.**
14aa0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 the constraint p
14ab0 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 roblem so INSERT
14ac0 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c OR REPLACE will
14ad0 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a always change.*
14ae0 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c * the return val
14af0 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 ue of this inter
14b00 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 face.)^.**.** ^F
14b10 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 or the purposes
14b20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
14b30 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 an [INSERT] is
14b40 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a considered to.**
14b50 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 be successful e
14b60 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 ven if it is sub
14b70 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 sequently rolled
14b80 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 back..**.** Thi
14b90 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 s function is ac
14ba0 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 cessible to SQL
14bb0 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 statements via t
14bc0 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 he.** [last_inse
14bd0 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 rt_rowid() SQL f
14be0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
14bf0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
14c00 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 read performs a
14c10 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 new [INSERT] on
14c20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 the same.** data
14c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
14c40 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 while the [sqlit
14c50 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
14c60 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 owid()].** funct
14c70 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 ion is running a
14c80 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 nd thus changes
14c90 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 the last insert
14ca0 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e [rowid],.** then
14cb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
14cc0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
14cd0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
14ce0 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 d()] is.** unpre
14cf0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 dictable and mig
14d00 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 ht not equal eit
14d10 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 her the old or t
14d20 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 he new.** last i
14d30 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a nsert [rowid]..*
14d40 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
14d50 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
14d60 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
14d70 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a owid(sqlite3*);.
14d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
14d90 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 Count The Numbe
14da0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
14db0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 ed.**.** ^This f
14dc0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
14dd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 the number of da
14de0 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 tabase rows that
14df0 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a were changed.**
14e00 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 or inserted or
14e10 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d deleted by the m
14e20 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d ost recently com
14e30 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 pleted SQL state
14e40 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b ment.** on the [
14e50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14e60 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 ion] specified b
14e70 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 y the first para
14e80 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 meter..** ^(Only
14e90 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 changes that ar
14ea0 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 e directly speci
14eb0 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 fied by the [INS
14ec0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a ERT], [UPDATE],.
14ed0 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 ** or [DELETE] s
14ee0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 tatement are cou
14ef0 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 nted. Auxiliary
14f00 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
14f10 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f by.** triggers o
14f20 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 r [foreign key a
14f30 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 ctions] are not
14f40 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 counted.)^ Use t
14f50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 he.** [sqlite3_t
14f60 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
14f70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 function to find
14f80 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 the total numbe
14f90 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 r of changes.**
14fa0 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 including change
14fb0 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 s caused by trig
14fc0 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e gers and foreign
14fd0 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a key actions..**
14fe0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 .** ^Changes to
14ff0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 a view that are
15000 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 simulated by an
15010 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
15020 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 ger].** are not
15030 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 counted. Only r
15040 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 eal table change
15050 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a s are counted..*
15060 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 *.** ^(A "row ch
15070 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 ange" is a chang
15080 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f e to a single ro
15090 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 w of a single ta
150a0 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 ble.** caused by
150b0 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 an INSERT, DELE
150c0 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 TE, or UPDATE st
150d0 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 atement. Rows t
150e0 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 hat.** are chang
150f0 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 ed as side effec
15100 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 ts of [REPLACE]
15110 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c constraint resol
15120 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 ution,.** rollba
15130 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 ck, ABORT proces
15140 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c sing, [DROP TABL
15150 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 E], or by any ot
15160 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d her.** mechanism
15170 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 s do not count a
15180 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 s direct row cha
15190 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 nges.)^.**.** A
151a0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 "trigger context
151b0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 " is a scope of
151c0 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 execution that b
151d0 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 egins and.** end
151e0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 s with the scrip
151f0 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 t of a [CREATE T
15200 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 RIGGER | trigger
15210 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 ]. .** Most SQL
15220 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a statements are.*
15230 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 * evaluated outs
15240 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 ide of any trigg
15250 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 er. This is the
15260 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 "top level".**
15270 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e trigger context.
15280 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 If a trigger f
15290 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f ires from the to
152a0 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 p level, a.** ne
152b0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 w trigger contex
152c0 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 t is entered for
152d0 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 the duration of
152e0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 that one.** tri
152f0 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 gger. Subtrigge
15300 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e rs create subcon
15310 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 texts for their
15320 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 duration..**.**
15330 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 ^Calling [sqlite
15340 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 3_exec()] or [sq
15350 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
15360 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a cursively does.*
15370 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e * not create a n
15380 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
15390 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 xt..**.** ^This
153a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
153b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
153c0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 irect row change
153d0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 s in the.** most
153e0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 recent INSERT,
153f0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
15400 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
15410 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 in the same.** t
15420 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a rigger context..
15430 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 **.** ^Thus, whe
15440 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 n called from th
15450 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 e top level, thi
15460 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
15470 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 ns the.** number
15480 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 of changes in t
15490 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 he most recent I
154a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
154b0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
154c0 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 also occurred a
154d0 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e t the top level.
154e0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 ^(Within the b
154f0 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 ody of a trigger
15500 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 ,.** the sqlite3
15510 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 _changes() inter
15520 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c face can be call
15530 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e ed to find the n
15540 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e umber of.** chan
15550 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 ges in the most
15560 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 recently complet
15570 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 ed INSERT, UPDAT
15580 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
15590 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
155a0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 the body of the
155b0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a same trigger..*
155c0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e * However, the n
155d0 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 umber returned d
155e0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
155f0 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 changes.** cause
15600 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 d by subtriggers
15610 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 since those hav
15620 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 e their own cont
15630 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 ext.)^.**.** See
15640 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 also the [sqlit
15650 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
15660 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 ()] interface, t
15670 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 he.** [count_cha
15680 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e nges pragma], an
15690 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 d the [changes()
156a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a SQL function]..
156b0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 **.** If a separ
156c0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 ate thread makes
156d0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 changes on the
156e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
156f0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c nnection.** whil
15700 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
15710 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
15720 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
15730 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 returned.** is u
15740 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
15750 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e not meaningful.
15760 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
15770 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
15780 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
15790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
157a0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
157b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
157c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
157d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
157e0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e mber of row chan
157f0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 ges caused by [I
15800 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 NSERT],.** [UPDA
15810 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 TE] or [DELETE]
15820 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 statements since
15830 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
15840 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f onnection] was o
15850 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 pened..** ^(The
15860 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 count returned b
15870 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f y sqlite3_total_
15880 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 changes() includ
15890 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a es all changes.*
158a0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 * from all [CREA
158b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
158c0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 gger] contexts a
158d0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 nd changes made
158e0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b by.** [foreign k
158f0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 ey actions]. How
15900 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 ever,.** the cou
15910 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c nt does not incl
15920 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 ude changes used
15930 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 to implement [R
15940 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 EPLACE] constrai
15950 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 nts,.** do rollb
15960 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 acks or ABORT pr
15970 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 ocessing, or [DR
15980 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 OP TABLE] proces
15990 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f sing. The.** co
159a0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
159b0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 lude rows of vie
159c0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 ws that fire an
159d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
159e0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 ger],.** though
159f0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f if the INSTEAD O
15a00 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 F trigger makes
15a10 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f changes of its o
15a20 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 wn, those change
15a30 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 s .** are counte
15a40 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c d.)^.** ^The sql
15a50 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
15a60 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f es() function co
15a70 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 unts the changes
15a80 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 as soon as.** t
15a90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
15aa0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 t makes them is
15ab0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 completed (when
15ac0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
15ad0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 ndle.** is passe
15ae0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 d to [sqlite3_re
15af0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
15b00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e e3_finalize()]).
15b10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
15b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
15b30 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
15b40 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
15b50 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
15b60 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c , and the [total
15b70 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 _changes() SQL f
15b80 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
15b90 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
15ba0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
15bb0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
15bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15bd0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
15be0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
15bf0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
15c00 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a then the value.
15c10 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 ** returned is u
15c20 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
15c30 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e not meaningful.
15c40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
15c50 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c nt sqlite3_total
15c60 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
15c70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
15c80 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 REF: Interrupt A
15c90 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 Long-Running Qu
15ca0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ery.**.** ^This
15cb0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
15cc0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
15cd0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
15ce0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
15cf0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
15d00 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
15d10 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
15d20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
15d30 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
15d40 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
15d50 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
15d60 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
15d70 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
15d80 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
15d90 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
15da0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
15db0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
15dc0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 *.** ^It is safe
15dd0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
15de0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 utine from a thr
15df0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 ead different fr
15e00 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 om the.** thread
15e10 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 that is current
15e20 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 ly running the d
15e30 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
15e40 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 n. But it.** is
15e50 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c not safe to cal
15e60 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 l this routine w
15e70 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
15e80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
15e90 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 .** is closed or
15ea0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 might close bef
15eb0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ore sqlite3_inte
15ec0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
15ed0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 .**.** ^If an SQ
15ee0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 L operation is v
15ef0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 ery nearly finis
15f00 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 hed at the time
15f10 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f when.** sqlite3_
15f20 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 interrupt() is c
15f30 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d alled, then it m
15f40 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e ight not have an
15f50 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 opportunity.**
15f60 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 to be interrupte
15f70 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 d and might cont
15f80 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 inue to completi
15f90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 on..**.** ^An SQ
15fa0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 L operation that
15fb0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 is interrupted
15fc0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
15fd0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
15fe0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 ** ^If the inter
15ff0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 rupted SQL opera
16000 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 tion is an INSER
16010 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
16020 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 LETE.** that is
16030 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 inside an explic
16040 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
16050 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 then the entire
16060 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 transaction.** w
16070 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ill be rolled ba
16080 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
16090 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
160a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 ite3_interrupt(D
160b0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 ) call is in eff
160c0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 ect until all cu
160d0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a rrently running.
160e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
160f0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
16100 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d onnection] D com
16110 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 plete. ^Any new
16120 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
16130 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
16140 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
16150 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
16160 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 ) call and befor
16170 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e e the .** runnin
16180 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 g statements rea
16190 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e ches zero are in
161a0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 terrupted as if
161b0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a they had been.**
161c0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 running prior t
161d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e o the sqlite3_in
161e0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 terrupt() call.
161f0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d ^New SQL statem
16200 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
16210 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
16220 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 he running state
16230 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 ment count reach
16240 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e es zero are.** n
16250 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 ot effected by t
16260 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
16270 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 rupt()..** ^A ca
16280 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
16290 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 terrupt(D) that
162a0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 occurs when ther
162b0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 e are no running
162c0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
162d0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e ts is a no-op an
162e0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 d has no effect
162f0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
16300 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
16310 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
16320 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
16330 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 t() call returns
16340 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 ..**.** If the d
16350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16360 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 on closes while
16370 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
16380 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e pt()].** is runn
16390 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 ing then bad thi
163a0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ngs will likely
163b0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 happen..*/.SQLIT
163c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
163d0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c e3_interrupt(sql
163e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
163f0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 API3REF: Determi
16400 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 ne If An SQL Sta
16410 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 tement Is Comple
16420 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 te.**.** These r
16430 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 outines are usef
16440 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e ul during comman
16450 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 d-line input to
16460 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 determine if the
16470 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e .** currently en
16480 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 tered text seems
16490 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c to form a compl
164a0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
164b0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 t or.** if addit
164c0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e ional input is n
164d0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e eeded before sen
164e0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e ding the text in
164f0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 to.** SQLite for
16500 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 parsing. ^Thes
16510 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
16520 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 n 1 if the input
16530 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 string.** appea
16540 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c rs to be a compl
16550 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
16560 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 t. ^A statement
16570 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 is judged to be
16580 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 .** complete if
16590 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 it ends with a s
165a0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 emicolon token a
165b0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 nd is not a pref
165c0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d ix of a.** well-
165d0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 formed CREATE TR
165e0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e IGGER statement.
165f0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 ^Semicolons th
16600 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 at are embedded
16610 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 within.** string
16620 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f literals or quo
16630 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e ted identifier n
16640 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 ames or comments
16650 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 are not.** inde
16660 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 pendent tokens (
16670 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 they are part of
16680 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 the token in wh
16690 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 ich they are.**
166a0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 embedded) and th
166b0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 us do not count
166c0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 as a statement t
166d0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 erminator. ^Whi
166e0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 tespace.** and c
166f0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c omments that fol
16700 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 low the final se
16710 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f micolon are igno
16720 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 red..**.** ^Thes
16730 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
16740 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 n 0 if the state
16750 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 ment is incomple
16760 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 te. ^If a.** me
16770 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
16780 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 fails, then SQLI
16790 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 TE_NOMEM is retu
167a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rned..**.** ^The
167b0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e se routines do n
167c0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c ot parse the SQL
167d0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 statements thus
167e0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 .** will not det
167f0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c ect syntacticall
16800 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e y incorrect SQL.
16810 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 .**.** ^(If SQLi
16820 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 te has not been
16830 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e initialized usin
16840 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 g [sqlite3_initi
16850 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a alize()] prior .
16860 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 ** to invoking s
16870 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
16880 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 6() then sqlite3
16890 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
168a0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f invoked.** auto
168b0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
168c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
168d0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 ). If that init
168e0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 ialization fails
168f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 ,.** then the re
16900 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
16910 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
16920 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 16() will be non
16930 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c -zero.** regardl
16940 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
16950 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 r not the input
16960 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e SQL is complete.
16970 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 )^.**.** The inp
16980 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
16990 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 omplete()] must
169a0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e be a zero-termin
169b0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 ated.** UTF-8 st
169c0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ring..**.** The
169d0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
169e0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
169f0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
16a00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
16a10 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 -16 string in na
16a20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
16a30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
16a40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c nt sqlite3_compl
16a50 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a ete(const char *
16a60 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 sql);.SQLITE_API
16a70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d int sqlite3_com
16a80 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f plete16(const vo
16a90 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a id *sql);../*.**
16aa0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
16ab0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 ter A Callback T
16ac0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f o Handle SQLITE_
16ad0 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a BUSY Errors.**.*
16ae0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
16af0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
16b00 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 function that mi
16b10 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
16b20 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
16b30 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
16b40 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 open a database
16b50 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 table that anot
16b60 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
16b70 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 process has loc
16b80 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ked..**.** ^If t
16b90 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
16ba0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b is NULL, then [
16bb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
16bc0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
16bd0 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 OCKED].** is ret
16be0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
16bf0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 y upon encounter
16c00 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e ing the lock. ^
16c10 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
16c20 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e back.** is not N
16c30 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 ULL, then the ca
16c40 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 llback might be
16c50 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f invoked with two
16c60 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a arguments..**.*
16c70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
16c80 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 ument to the bus
16c90 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 y handler is a c
16ca0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
16cb0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
16cc0 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
16cd0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
16ce0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
16cf0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ). ^The second
16d00 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
16d10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
16d20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
16d30 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
16d40 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
16d50 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
16d60 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 n invoked for th
16d70 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 is locking event
16d80 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 . ^If the.** bu
16d90 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 sy callback retu
16da0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 rns 0, then no a
16db0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 dditional attemp
16dc0 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a ts are made to.*
16dd0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 * access the dat
16de0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 abase and [SQLIT
16df0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
16e00 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
16e10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
16e20 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 * ^If the callba
16e30 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
16e40 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 ero, then anothe
16e50 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 r attempt.** is
16e60 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 made to open the
16e70 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 database for re
16e80 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 ading and the cy
16e90 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a cle repeats..**.
16ea0 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 ** The presence
16eb0 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 of a busy handle
16ec0 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 r does not guara
16ed0 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c ntee that it wil
16ee0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 l be invoked.**
16ef0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f when there is lo
16f00 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e ck contention. ^
16f10 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d If SQLite determ
16f20 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 ines that invoki
16f30 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 ng the busy.** h
16f40 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 andler could res
16f50 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 ult in a deadloc
16f60 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 k, it will go ah
16f70 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b ead and return [
16f80 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 SQLITE_BUSY].**
16f90 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
16fa0 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 _BLOCKED] instea
16fb0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 d of invoking th
16fc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
16fd0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 ** Consider a sc
16fe0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 enario where one
16ff0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
17000 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 ing a read lock
17010 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 that.** it is tr
17020 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 ying to promote
17030 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f to a reserved lo
17040 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f ck and.** a seco
17050 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f nd process is ho
17060 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 lding a reserved
17070 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 lock that it is
17080 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 trying.** to pr
17090 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c omote to an excl
170a0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 usive lock. The
170b0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 first process c
170c0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a annot proceed.**
170d0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
170e0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 locked by the se
170f0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 cond and the sec
17100 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e ond process cann
17110 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 ot.** proceed be
17120 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
17130 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ked by the first
17140 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 . If both proce
17150 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 sses.** invoke t
17160 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 he busy handlers
17170 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d , neither will m
17180 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 ake any progress
17190 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a . Therefore,.**
171a0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 SQLite returns
171b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f [SQLITE_BUSY] fo
171c0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 r the first proc
171d0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 ess, hoping that
171e0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e this.** will in
171f0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 duce the first p
17200 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 rocess to releas
17210 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 e its read lock
17220 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 and allow.** the
17230 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
17240 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a to proceed..**.*
17250 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 * ^The default b
17260 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
17270 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
17280 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 [SQLITE_BUSY] e
17290 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 rror is converte
172a0 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 d to [SQLITE_IOE
172b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 RR_BLOCKED].** w
172c0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e hen SQLite is in
172d0 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 the middle of a
172e0 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 large transacti
172f0 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 on where all the
17300 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c .** changes will
17310 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 not fit into th
17320 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 e in-memory cach
17330 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a e. SQLite will.
17340 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 ** already hold
17350 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 a RESERVED lock
17360 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 on the database
17370 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 file, but it nee
17380 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 ds.** to promote
17390 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 this lock to EX
173a0 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 CLUSIVE so that
173b0 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 it can spill cac
173c0 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f he.** pages into
173d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
173e0 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 le without harm
173f0 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a to concurrent.**
17400 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 readers. ^If i
17410 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 t is unable to p
17420 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c romote the lock,
17430 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d then the in-mem
17440 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c ory.** cache wil
17450 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 l be left in an
17460 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 inconsistent sta
17470 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 te and so the er
17480 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 ror.** code is p
17490 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 romoted from the
174a0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 relatively beni
174b0 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d gn [SQLITE_BUSY]
174c0 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 to.** the more
174d0 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 severe [SQLITE_I
174e0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 OERR_BLOCKED].
174f0 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 ^This error code
17500 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f promotion.** fo
17510 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 rces an automati
17520 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 c rollback of th
17530 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 e changes. See
17540 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
17550 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d /cvstrac/wiki?p=
17560 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 CorruptionFollow
17570 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a ingBusyError">.*
17580 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c * CorruptionFoll
17590 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f owingBusyError</
175a0 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 a> wiki page for
175b0 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 a discussion of
175c0 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 why.** this is
175d0 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a important..**.**
175e0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
175f0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
17600 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
17610 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
17620 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17630 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
17640 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
17650 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
17660 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
17670 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 andler.)^ ^Note
17680 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 that calling [s
17690 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
176a0 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 out()].** will a
176b0 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 lso set or clear
176c0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
176d0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 r..**.** The bus
176e0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c y callback shoul
176f0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 d not take any a
17700 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 ctions which mod
17710 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ify the.** datab
17720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
17730 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
17740 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 busy handler. A
17750 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a ny such actions.
17760 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 ** result in und
17770 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
17780 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 .** .** A busy h
17790 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
177a0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
177b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
177c0 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 or [prepared st
177d0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e atement] that in
177e0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
177f0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 andler..*/.SQLIT
17800 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
17810 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 3_busy_handler(s
17820 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
17830 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 void*,int), void
17840 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
17850 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 REF: Set A Busy
17860 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 Timeout.**.** ^T
17870 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 his routine sets
17880 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 a [sqlite3_busy
17890 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 _handler | busy
178a0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c handler] that sl
178b0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 eeps.** for a sp
178c0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f ecified amount o
178d0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 f time when a ta
178e0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 ble is locked.
178f0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 ^The handler.**
17900 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 will sleep multi
17910 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 ple times until
17920 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 at least "ms" mi
17930 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
17940 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 eeping.** have a
17950 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 ccumulated. ^Af
17960 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 ter at least "ms
17970 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
17980 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 f sleeping,.** t
17990 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 he handler retur
179a0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 ns 0 which cause
179b0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 s [sqlite3_step(
179c0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 )] to return.**
179d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 [SQLITE_BUSY] or
179e0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
179f0 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e LOCKED]..**.** ^
17a00 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
17a10 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 tine with an arg
17a20 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 ument less than
17a30 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
17a40 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c .** turns off al
17a50 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e l busy handlers.
17a60 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 .**.** ^(There c
17a70 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e an only be a sin
17a80 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 gle busy handler
17a90 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
17aa0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
17ab0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 onnection] any a
17ac0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e ny given moment.
17ad0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 If another bus
17ae0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 y handler.** was
17af0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 defined (using
17b00 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 [sqlite3_busy_h
17b10 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 andler()]) prior
17b20 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 to calling.** t
17b30 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 his routine, tha
17b40 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e t other busy han
17b50 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e dler is cleared.
17b60 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 )^.*/.SQLITE_API
17b70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 int sqlite3_bus
17b80 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 y_timeout(sqlite
17b90 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 3*, int ms);../*
17ba0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
17bb0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e nvenience Routin
17bc0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 es For Running Q
17bd0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 ueries.**.** Thi
17be0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e s is a legacy in
17bf0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 terface that is
17c00 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 preserved for ba
17c10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
17c20 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 ility..** Use of
17c30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
17c40 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 is not recommend
17c50 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 ed..**.** Defini
17c60 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c tion: A <b>resul
17c70 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d t table</b> is m
17c80 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 emory data struc
17c90 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 ture created by
17ca0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
17cb0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 get_table()] int
17cc0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c erface. A resul
17cd0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 t table records
17ce0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 the.** complete
17cf0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 query results fr
17d00 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 om one or more q
17d10 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ueries..**.** Th
17d20 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 e table conceptu
17d30 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 ally has a numbe
17d40 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f r of rows and co
17d50 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 lumns. But.** t
17d60 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 hese numbers are
17d70 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 not part of the
17d80 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 result table it
17d90 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 self. These.**
17da0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 numbers are obta
17db0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e ined separately.
17dc0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e Let N be the n
17dd0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a umber of rows.**
17de0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 and M be the nu
17df0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e mber of columns.
17e00 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
17e10 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 table is an arra
17e20 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
17e30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
17e40 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a UTF-8 strings..
17e50 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b ** There are (N+
17e60 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 1)*M elements in
17e70 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 the array. The
17e80 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 first M pointer
17e90 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 s point.** to ze
17ea0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
17eb0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 rings that cont
17ec0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 ain the names of
17ed0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a the columns..**
17ee0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 The remaining e
17ef0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 ntries all point
17f00 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 to query result
17f10 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 s. NULL values
17f20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c result.** in NUL
17f30 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c L pointers. All
17f40 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 other values ar
17f50 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 e in their UTF-8
17f60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
17f70 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 .** string repre
17f80 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 sentation as ret
17f90 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
17fa0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
17fb0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
17fc0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e table might con
17fd0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d sist of one or m
17fe0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ore memory alloc
17ff0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 ations..** It is
18000 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 not safe to pas
18010 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
18020 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 directly to [sq
18030 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
18040 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
18050 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c should be deall
18060 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 ocated using [sq
18070 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
18080 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 ()]..**.** ^(As
18090 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 an example of th
180a0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 e result table f
180b0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 ormat, suppose a
180c0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a query result.**
180d0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
180e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
180f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
18100 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 Name |
18110 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d Age.** --
18120 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
18130 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 -----.**
18140 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 Alice | 43
18150 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 .** Bob
18160 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 | 28.**
18170 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 Cindy
18180 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e | 21.** </pre>
18190 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
181a0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 .** There are tw
181b0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 o column (M==2)
181c0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 and three rows (
181d0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 N==3). Thus the
181e0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 .** result table
181f0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 has 8 entries.
18200 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 Suppose the res
18210 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f ult table is sto
18220 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 red.** in an arr
18230 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c ay names azResul
18240 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c t. Then azResul
18250 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e t holds this con
18260 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f tent:.**.** <blo
18270 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
18280 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
18290 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 [0] = "Name"
182a0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
182b0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 sult[1] = "A
182c0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ge";.** a
182d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d zResult[2] =
182e0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 "Alice";.**
182f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
18300 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 ;3] = "43";.**
18310 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
18320 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 91;4] = "Bob";.*
18330 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
18340 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b t[5] = "28";
18350 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
18360 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 ult[6] = "Ci
18370 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ndy";.**
18380 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 azResult[7]
18390 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 = "21";.** </pre
183a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e ></blockquote>)^
183b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
183c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
183d0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 function evaluat
183e0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a es one or more.*
183f0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 * semicolon-sepa
18400 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d rated SQL statem
18410 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f ents in the zero
18420 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
18430 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 8.** string of i
18440 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ts 2nd parameter
18450 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 and returns a r
18460 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 esult table to t
18470 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 he.** pointer gi
18480 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 ven in its 3rd p
18490 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
184a0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 After the applic
184b0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 ation has finish
184c0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 ed with the resu
184d0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f lt from sqlite3_
184e0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 get_table(),.**
184f0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 it must pass the
18500 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f result table po
18510 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 inter to sqlite3
18520 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e _free_table() in
18530 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c order to.** rel
18540 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
18550 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 that was malloce
18560 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 d. Because of t
18570 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 he way the.** [s
18580 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
18590 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 happens within
185a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
185b0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 e(), the calling
185c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
185d0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c t not try to cal
185e0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 l [sqlite3_free(
185f0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e )] directly. On
18600 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ly.** [sqlite3_f
18610 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 ree_table()] is
18620 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 able to release
18630 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 the memory prope
18640 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a rly and safely..
18650 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
18660 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 3_get_table() in
18670 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 terface is imple
18680 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 mented as a wrap
18690 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
186a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 qlite3_exec()].
186b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
186c0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 _table() routine
186d0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 does not have a
186e0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 ccess.** to any
186f0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 internal data st
18700 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 ructures of SQLi
18710 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c te. It uses onl
18720 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 y the public.**
18730 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 interface define
18740 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f d here. As a co
18750 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 nsequence, error
18760 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 s that occur in
18770 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c the.** wrapper l
18780 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 ayer outside of
18790 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 the internal [sq
187a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 lite3_exec()] ca
187b0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 ll are not.** re
187c0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 flected in subse
187d0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
187e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
187f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
18800 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 3_errmsg()]..*/.
18810 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
18820 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
18830 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
18840 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
18850 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
18860 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
18870 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 Sql, /* SQL
18880 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 to be evaluated
18890 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a */. char ***paz
188a0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 Result, /* Re
188b0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 sults of the que
188c0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 ry */. int *pnR
188d0 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a ow, /*
188e0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
188f0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 t rows written h
18900 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ere */. int *pn
18910 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f Column, /
18920 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
18930 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 lt columns writt
18940 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 en here */. cha
18950 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 r **pzErrmsg
18960 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
18970 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
18980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
18990 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f id sqlite3_free_
189a0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 table(char **res
189b0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ult);../*.** CAP
189c0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 I3REF: Formatted
189d0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 String Printing
189e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
189f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
18a00 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 are work-alikes
18a10 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 of the "printf()
18a20 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 " family of func
18a30 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 tions.** from th
18a40 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
18a50 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rary..**.** ^The
18a60 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
18a70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 () and sqlite3_v
18a80 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e mprintf() routin
18a90 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a es write their.*
18aa0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d * results into m
18ab0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
18ac0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
18ad0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 loc()]..** The s
18ae0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
18af0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 by these two rou
18b00 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a tines should be.
18b10 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b ** released by [
18b20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
18b30 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 ^Both routines
18b40 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c return a.** NUL
18b50 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 L pointer if [sq
18b60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
18b70 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
18b80 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 ocate enough.**
18b90 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
18ba0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
18bb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ing..**.** ^(The
18bc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
18bd0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 f() routine is s
18be0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 imilar to "snpri
18bf0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 ntf()" from.** t
18c00 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
18c10 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 brary. The resu
18c20 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e lt is written in
18c30 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 to the.** buffer
18c40 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 supplied as the
18c50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
18c60 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 r whose size is
18c70 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 given by.** the
18c80 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
18c90 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f Note that the o
18ca0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 rder of the.** f
18cb0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 irst two paramet
18cc0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 ers is reversed
18cd0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e from snprintf().
18ce0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a )^ This is an.*
18cf0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 * historical acc
18d00 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f ident that canno
18d10 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f t be fixed witho
18d20 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 ut breaking.** b
18d30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
18d40 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 bility. ^(Note
18d50 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 also that sqlite
18d60 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
18d70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
18d80 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 r to its buffer
18d90 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e instead of the n
18da0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 umber of.** char
18db0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 acters actually
18dc0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
18dd0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 buffer.)^ We a
18de0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
18df0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
18e00 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
18e10 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
18e20 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
18e30 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
18e40 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
18e50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
18e60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
18e70 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
18e80 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
18e90 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
18ea0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 ^As long as the
18eb0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 buffer size is g
18ec0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f reater than zero
18ed0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e , sqlite3_snprin
18ee0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 tf().** guarante
18ef0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 es that the buff
18f00 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 er is always zer
18f10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e o-terminated. ^
18f20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 The first.** par
18f30 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 ameter "n" is th
18f40 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 e total size of
18f50 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c the buffer, incl
18f60 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a uding space for.
18f70 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d ** the zero term
18f80 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 inator. So the
18f90 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 longest string t
18fa0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c hat can be compl
18fb0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e etely.** written
18fc0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 will be n-1 cha
18fd0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e racters..**.** ^
18fe0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 The sqlite3_vsnp
18ff0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
19000 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 is a varargs ver
19010 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f sion of sqlite3_
19020 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a snprintf()..**.*
19030 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
19040 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 all implement s
19050 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ome additional f
19060 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 ormatting.** opt
19070 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 ions that are us
19080 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 eful for constru
19090 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d cting SQL statem
190a0 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 ents..** All of
190b0 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 the usual printf
190c0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 () formatting op
190d0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e tions apply. In
190e0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 addition, there
190f0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c .** is are "%q",
19100 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 "%Q", and "%z"
19110 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e options..**.** ^
19120 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 (The %q option w
19130 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 orks like %s in
19140 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 that it substitu
19150 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e tes a nul-termin
19160 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 ated.** string f
19170 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 rom the argument
19180 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 list. But %q a
19190 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 lso doubles ever
191a0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 y '\'' character
191b0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 ..** %q is desig
191c0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ned for use insi
191d0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 de a string lite
191e0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c ral.)^ By doubl
191f0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a ing each '\''.**
19200 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 character it es
19210 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 capes that chara
19220 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 cter and allows
19230 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 it to be inserte
19240 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 d into.** the st
19250 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 ring..**.** For
19260 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 example, assume
19270 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 the string varia
19280 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 ble zText contai
19290 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f ns text as follo
192a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
192b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
192c0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 char *zText = "I
192d0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
192e0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
192f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
19300 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 One can use this
19310 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 text in an SQL
19320 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c statement as fol
19330 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
19340 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
19350 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
19360 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
19370 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
19380 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c e VALUES('%q')",
19390 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
193a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
193b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
193c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
193d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
193e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
193f0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 ** Because the %
19400 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 q format string
19410 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 is used, the '\'
19420 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a ' character in z
19430 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 Text.** is escap
19440 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 ed and the SQL g
19450 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 enerated is as f
19460 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
19470 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
19480 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
19490 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
194a0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 t''s a happy day
194b0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !').** </pre></b
194c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
194d0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 This is correct
194e0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 . Had we used %
194f0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c s instead of %q,
19500 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 the generated S
19510 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 QL.** would have
19520 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 looked like thi
19530 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
19540 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
19550 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
19560 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 1 VALUES('It's a
19570 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a happy day!');.*
19580 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
19590 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
195a0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
195b0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 is an SQL syntax
195c0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 error. As a ge
195d0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 neral rule you s
195e0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 hould.** always
195f0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f use %q instead o
19600 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 f %s when insert
19610 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 ing text into a
19620 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a string literal..
19630 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f **.** ^(The %Q o
19640 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
19650 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c %q except it al
19660 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 so adds single q
19670 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 uotes around.**
19680 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 the outside of t
19690 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e he total string.
196a0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 Additionally,
196b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
196c0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d in the.** argum
196d0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 ent list is a NU
196e0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 LL pointer, %Q s
196f0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 ubstitutes the t
19700 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 ext "NULL" (with
19710 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 out.** single qu
19720 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f otes).)^ So, fo
19730 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 r example, one c
19740 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 ould say:.**.**
19750 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
19760 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
19770 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
19780 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
19790 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 table VALUES(%Q)
197a0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
197b0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
197c0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
197d0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
197e0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
197f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
19800 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 *.** The code ab
19810 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 ove will render
19820 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 a correct SQL st
19830 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a atement in the z
19840 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 SQL.** variable
19850 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 even if the zTex
19860 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 t variable is a
19870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
19880 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 .** ^(The "%z" f
19890 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
198a0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 works like "%s"
198b0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a but with the.**
198c0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 addition that a
198d0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 fter the string
198e0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e has been read an
198f0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a d copied into.**
19900 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 the result, [sq
19910 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 lite3_free()] is
19920 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 called on the i
19930 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a nput string.)^.*
19940 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 /.SQLITE_API cha
19950 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e r *sqlite3_mprin
19960 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e tf(const char*,.
19970 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..);.SQLITE_API
19980 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d char *sqlite3_vm
19990 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
199a0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 r*, va_list);.SQ
199b0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 LITE_API char *s
199c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
199d0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
199e0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c char*, ...);.SQL
199f0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 ITE_API char *sq
19a00 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
19a10 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
19a20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
19a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
19a40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
19a50 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
19a60 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
19a70 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
19a80 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
19a90 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
19aa0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
19ab0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
19ac0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
19ad0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
19ae0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
19af0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
19b00 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
19b10 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
19b20 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
19b30 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
19b40 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
19b50 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
19b60 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
19b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
19b80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
19b90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
19ba0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
19bb0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
19bc0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
19bd0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
19be0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
19bf0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
19c00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
19c10 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
19c20 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
19c30 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
19c40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
19c50 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
19c60 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
19c70 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
19c80 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
19c90 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
19ca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
19cb0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
19cc0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ointer..**.** ^C
19cd0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 alling sqlite3_f
19ce0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 ree() with a poi
19cf0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 nter previously
19d00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
19d10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
19d20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
19d30 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 oc() releases th
19d40 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 at memory so.**
19d50 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 that it might be
19d60 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 reused. ^The s
19d70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f qlite3_free() ro
19d80 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f utine is.** a no
19d90 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 -op if is called
19da0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
19db0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 nter. Passing a
19dc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
19dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
19de0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 () is harmless.
19df0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 After being fre
19e00 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 ed, memory.** sh
19e10 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 ould neither be
19e20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e read nor written
19e30 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 . Even reading
19e40 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 previously freed
19e50 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 .** memory might
19e60 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 result in a seg
19e70 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 mentation fault
19e80 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
19e90 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 error..** Memory
19ea0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 corruption, a s
19eb0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
19ec0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 t, or other seve
19ed0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 re error.** migh
19ee0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 t result if sqli
19ef0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 te3_free() is ca
19f00 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d lled with a non-
19f10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 NULL pointer tha
19f20 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 t.** was not obt
19f30 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
19f40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
19f50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
19f60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
19f70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
19f80 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
19f90 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
19fa0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
19fb0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
19fc0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
19fd0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
19fe0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
19ff0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 eter. The memor
1a000 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
1a010 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 be resized is th
1a020 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
1a030 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 eter.)^ ^ If the
1a040 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1a050 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
1a060 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 loc().** is a NU
1a070 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
1a080 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 its behavior is
1a090 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c identical to cal
1a0a0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
1a0b0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 malloc(N) where
1a0c0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
1a0d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1a0e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
1a0f0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e ** ^If the secon
1a100 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
1a110 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1a120 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
1a130 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
1a140 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
1a150 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
1a160 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1a170 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 te3_free(P) wher
1a180 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 e P is the first
1a190 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1a1a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
1a1b0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 .** ^sqlite3_rea
1a1c0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 lloc() returns a
1a1d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
1a1e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
1a1f0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e ** of at least N
1a200 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f bytes in size o
1a210 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 r NULL if suffic
1a220 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 ient memory is u
1a230 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e navailable..** ^
1a240 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 If M is the size
1a250 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
1a260 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d location, then m
1a270 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a in(N,M) bytes.**
1a280 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
1a290 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 location are cop
1a2a0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 ied into the beg
1a2b0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 inning of buffer
1a2c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
1a2d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1a2e0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 ) and the prior
1a2f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 allocation is fr
1a300 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 eed..** ^If sqli
1a310 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
1a320 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e turns NULL, then
1a330 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
1a340 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 ation.** is not
1a350 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 freed..**.** ^Th
1a360 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
1a370 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
1a380 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 loc() and sqlite
1a390 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 3_realloc().** i
1a3a0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 s always aligned
1a3b0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 to at least an
1a3c0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 8 byte boundary,
1a3d0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 or to a.** 4 by
1a3e0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 te boundary if t
1a3f0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 he [SQLITE_4_BYT
1a400 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 E_ALIGNED_MALLOC
1a410 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
1a420 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 * option is used
1a430 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 ..**.** In SQLit
1a440 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 e version 3.5.0
1a450 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 and 3.5.1, it wa
1a460 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 s possible to de
1a470 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 fine.** the SQLI
1a480 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
1a490 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 LLOCATION which
1a4a0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 would cause the
1a4b0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c built-in.** impl
1a4c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
1a4d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ese routines to
1a4e0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 be omitted. Tha
1a4f0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 t capability.**
1a500 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f is no longer pro
1a510 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 vided. Only bui
1a520 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
1a530 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 ocators can be u
1a540 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 sed..**.** Prior
1a550 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 to SQLite versi
1a560 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 on 3.7.10, the W
1a570 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 indows OS interf
1a580 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 ace layer called
1a590 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d .** the system m
1a5a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
1a5b0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e () directly when
1a5c0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 converting.** f
1a5d0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e ilenames between
1a5e0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 the UTF-8 encod
1a5f0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 ing used by SQLi
1a600 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 te.** and whatev
1a610 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f er filename enco
1a620 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 ding is used by
1a630 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 the particular W
1a640 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c indows.** instal
1a650 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 lation. Memory
1a660 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
1a670 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c s were detected,
1a680 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 but.** they wer
1a690 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 e reported back
1a6a0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f as [SQLITE_CANTO
1a6b0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 PEN] or.** [SQLI
1a6c0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 TE_IOERR] rather
1a6d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f than [SQLITE_NO
1a6e0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 MEM]..**.** The
1a6f0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 pointer argument
1a700 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 s to [sqlite3_fr
1a710 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ee()] and [sqlit
1a720 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
1a730 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
1a740 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 NULL or else poi
1a750 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 nters obtained f
1a760 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 rom a prior.** i
1a770 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
1a780 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
1a790 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
1a7a0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 loc()] that have
1a7b0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e .** not yet been
1a7c0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a released..**.**
1a7d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
1a7e0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f must not read o
1a7f0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 r write any part
1a800 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f of.** a block o
1a810 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 f memory after i
1a820 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 t has been relea
1a830 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 sed using.** [sq
1a840 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 lite3_free()] or
1a850 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
1a860 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f c()]..*/.SQLITE_
1a870 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
1a880 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 3_malloc(int);.S
1a890 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
1a8a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1a8b0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c void*, int);.SQL
1a8c0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
1a8d0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 ite3_free(void*)
1a8e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1a8f0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
1a900 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a tor Statistics.*
1a910 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 *.** SQLite prov
1a920 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 ides these two i
1a930 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 nterfaces for re
1a940 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 porting on the s
1a950 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 tatus.** of the
1a960 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1a970 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 )], [sqlite3_fre
1a980 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
1a990 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
1a9a0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 routines, which
1a9b0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d form the built-
1a9c0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
1a9d0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a tion subsystem..
1a9e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
1a9f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1aa00 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
1aa10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1aa20 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d bytes.** of mem
1aa30 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 ory currently ou
1aa40 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f tstanding (mallo
1aa50 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 ced but not free
1aa60 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c d)..** ^The [sql
1aa70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
1aa80 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 water()] routine
1aa90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 returns the max
1aaa0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 imum.** value of
1aab0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1aac0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 _used()] since t
1aad0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
1aae0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 rk.** was last r
1aaf0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 eset. ^The valu
1ab00 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b es returned by [
1ab10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1ab20 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 sed()] and.** [s
1ab30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1ab40 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 ghwater()] inclu
1ab50 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a de any overhead.
1ab60 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 ** added by SQLi
1ab70 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d te in its implem
1ab80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c entation of [sql
1ab90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a ite3_malloc()],.
1aba0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 ** but not overh
1abb0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 ead added by the
1abc0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 any underlying
1abd0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a system library.*
1abe0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
1abf0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1ac00 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a )] may call..**.
1ac10 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 ** ^The memory h
1ac20 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 igh-water mark i
1ac30 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 s reset to the c
1ac40 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a urrent value of.
1ac50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1ac60 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e ry_used()] if an
1ac70 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 d only if the pa
1ac80 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
1ac90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1aca0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 ghwater()] is tr
1acb0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 ue. ^The value
1acc0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b returned.** by [
1acd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1ace0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 ighwater(1)] is
1acf0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
1ad00 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 ark.** prior to
1ad10 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 the reset..*/.SQ
1ad20 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
1ad30 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d _int64 sqlite3_m
1ad40 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 emory_used(void)
1ad50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
1ad60 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
1ad70 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1ad80 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 ter(int resetFla
1ad90 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
1ada0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 REF: Pseudo-Rand
1adb0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 om Number Genera
1adc0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 tor.**.** SQLite
1add0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 contains a high
1ade0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d -quality pseudo-
1adf0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 random number ge
1ae00 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 nerator (PRNG) u
1ae10 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 sed to.** select
1ae20 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c random [ROWID |
1ae30 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e ROWIDs] when in
1ae40 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f serting new reco
1ae50 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 rds into a table
1ae60 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 that.** already
1ae70 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 uses the larges
1ae80 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 t possible [ROWI
1ae90 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 D]. The PRNG is
1aea0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a also used for.*
1aeb0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 * the build-in r
1aec0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 andom() and rand
1aed0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e omblob() SQL fun
1aee0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e ctions. This in
1aef0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a terface allows.*
1af00 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * applications t
1af10 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d o access the sam
1af20 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 e PRNG for other
1af30 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a purposes..**.**
1af40 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ^A call to this
1af50 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
1af60 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f N bytes of rando
1af70 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 mness into buffe
1af80 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 r P..**.** ^The
1af90 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 first time this
1afa0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b routine is invok
1afb0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 ed (either inter
1afc0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 nally or by.** t
1afd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 he application)
1afe0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 the PRNG is seed
1aff0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
1b000 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ess obtained.**
1b010 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d from the xRandom
1b020 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 ness method of t
1b030 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
1b040 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
1b050 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 .** ^On all subs
1b060 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
1b070 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 ns, the pseudo-r
1b080 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e andomness is gen
1b090 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e erated.** intern
1b0a0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 ally and without
1b0b0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 recourse to the
1b0c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 [sqlite3_vfs] x
1b0d0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 Randomness.** me
1b0e0 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f thod..*/.SQLITE_
1b0f0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
1b100 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 _randomness(int
1b110 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a N, void *P);../*
1b120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1b130 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f mpile-Time Autho
1b140 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 rization Callbac
1b150 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 ks.**.** ^This r
1b160 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 outine registers
1b170 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 an authorizer c
1b180 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 allback with a p
1b190 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 articular.** [da
1b1a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1b1b0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 n], supplied in
1b1c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
1b1d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 nt..** ^The auth
1b1e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1b1f0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 is invoked as SQ
1b200 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
1b210 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a being compiled.
1b220 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ** by [sqlite3_p
1b230 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
1b240 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 variants [sqlit
1b250 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1b260 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 ,.** [sqlite3_pr
1b270 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b epare16()] and [
1b280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1b290 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 6_v2()]. ^At va
1b2a0 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 rious.** points
1b2b0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 during the compi
1b2c0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 lation process,
1b2d0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e as logic is bein
1b2e0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 g created.** to
1b2f0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
1b300 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 actions, the aut
1b310 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1b320 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a is invoked to.*
1b330 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 * see if those a
1b340 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 ctions are allow
1b350 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 ed. ^The author
1b360 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
1b370 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
1b380 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c SQLITE_OK] to al
1b390 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 low the action,
1b3a0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1b3b0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a to disallow the.
1b3c0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 ** specific acti
1b3d0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 on but allow the
1b3e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1b3f0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 o continue to be
1b400 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 .** compiled, or
1b410 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 [SQLITE_DENY] t
1b420 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 o cause the enti
1b430 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
1b440 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 to be.** reject
1b450 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ed with an error
1b460 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f . ^If the autho
1b470 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
1b480 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
1b490 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
1b4a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
1b4b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
1b4c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
1b4d0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
1b4e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1b4f0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
1b500 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
1b510 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
1b520 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
1b530 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
1b540 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
1b550 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1b560 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
1b570 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
1b580 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
1b590 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
1b5a0 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 ^When the callb
1b5b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
1b5c0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a ITE_DENY], the.*
1b5d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1b5e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
1b5f0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
1b600 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a triggered the.*
1b610 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c * authorizer wil
1b620 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
1b630 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 rror message exp
1b640 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 laining that.**
1b650 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 access is denied
1b660 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 . .**.** ^The fi
1b670 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
1b680 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1b690 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
1b6a0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a py of the third.
1b6b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
1b6c0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
1b6d0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 authorizer() int
1b6e0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 erface. ^The sec
1b6f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ond parameter.**
1b700 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1b710 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b is an integer [
1b720 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 SQLITE_COPY | ac
1b730 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 tion code] that
1b740 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
1b750 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 particular acti
1b760 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
1b770 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 zed. ^The third
1b780 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 through sixth pa
1b790 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 rameters.** to t
1b7a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 he callback are
1b7b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1b7c0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e strings that con
1b7d0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a tain additional.
1b7e0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 ** details about
1b7f0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 the action to b
1b800 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a e authorized..**
1b810 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
1b820 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
1b830 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 TE_READ].** and
1b840 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
1b850 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e urns [SQLITE_IGN
1b860 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a ORE] then the.**
1b870 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1b880 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 ment] statement
1b890 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 is constructed t
1b8a0 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 o substitute.**
1b8b0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 a NULL value in
1b8c0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 place of the tab
1b8d0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 le column that w
1b8e0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 ould have.** bee
1b8f0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 n read if [SQLIT
1b900 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 E_OK] had been r
1b910 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 eturned. The [S
1b920 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a QLITE_IGNORE].**
1b930 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 return can be u
1b940 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 sed to deny an u
1b950 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 ntrusted user ac
1b960 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 cess to individu
1b970 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 al.** columns of
1b980 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 a table..** ^If
1b990 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
1b9a0 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 is [SQLITE_DELE
1b9b0 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c TE] and the call
1b9c0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
1b9d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1b9e0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 then the [DELETE
1b9f0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 ] operation proc
1ba00 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 eeds but the.**
1ba10 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 [truncate optimi
1ba20 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 zation] is disab
1ba30 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 led and all rows
1ba40 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 are deleted ind
1ba50 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a ividually..**.**
1ba60 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 An authorizer i
1ba70 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c s used when [sql
1ba80 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
1ba90 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c reparing].** SQL
1baa0 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d statements from
1bab0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f an untrusted so
1bac0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 urce, to ensure
1bad0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 that the SQL sta
1bae0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f tements.** do no
1baf0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 t try to access
1bb00 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f data they are no
1bb10 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 t allowed to see
1bb20 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 , or that they d
1bb30 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 o not.** try to
1bb40 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 execute maliciou
1bb50 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 s statements tha
1bb60 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 t damage the dat
1bb70 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 abase. For.** e
1bb80 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
1bb90 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 cation may allow
1bba0 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 a user to enter
1bbb0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 arbitrary.** SQ
1bbc0 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 L queries for ev
1bbd0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 aluation by a da
1bbe0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 tabase. But the
1bbf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 application doe
1bc00 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 s.** not want th
1bc10 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c e user to be abl
1bc20 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 e to make arbitr
1bc30 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ary changes to t
1bc40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 he.** database.
1bc50 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 An authorizer c
1bc60 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 ould then be put
1bc70 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 in place while
1bc80 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 the.** user-ente
1bc90 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 red SQL is being
1bca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1bcb0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 e | prepared] th
1bcc0 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 at.** disallows
1bcd0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 everything excep
1bce0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 t [SELECT] state
1bcf0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 ments..**.** App
1bd00 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e lications that n
1bd10 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 eed to process S
1bd20 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 QL from untruste
1bd30 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 d sources.** mig
1bd40 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 ht also consider
1bd50 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 lowering resour
1bd60 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 ce limits using
1bd70 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
1bd80 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e ].** and limitin
1bd90 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 g database size
1bda0 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 using the [max_p
1bdb0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 age_count] [PRAG
1bdc0 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 MA].** in additi
1bdd0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 on to using an a
1bde0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a uthorizer..**.**
1bdf0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 ^(Only a single
1be00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 authorizer can
1be10 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 be in place on a
1be20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1be30 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d tion.** at a tim
1be40 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f e. Each call to
1be50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
1be60 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 horizer override
1be70 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 s the.** previou
1be80 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 s call.)^ ^Disa
1be90 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a ble the authoriz
1bea0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 er by installing
1beb0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b a NULL callback
1bec0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 ..** The authori
1bed0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 zer is disabled
1bee0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a by default..**.*
1bef0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
1bf00 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e callback must n
1bf10 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
1bf20 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
1bf30 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
1bf40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
1bf50 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 invoked the auth
1bf60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e orizer callback.
1bf70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
1bf80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1bf90 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
1bfa0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
1bfb0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
1bfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1bfd0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
1bfe0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
1bff0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
1c000 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b h..**.** ^When [
1c010 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1c020 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f v2()] is used to
1c030 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 prepare a state
1c040 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 ment, the.** sta
1c050 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 tement might be
1c060 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 re-prepared duri
1c070 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
1c080 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a ()] due to a .**
1c090 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 schema change.
1c0a0 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c Hence, the appl
1c0b0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 ication should e
1c0c0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a nsure that the.*
1c0d0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 * correct author
1c0e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
1c0f0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 mains in place d
1c100 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 uring the [sqlit
1c110 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a e3_step()]..**.*
1c120 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 * ^Note that the
1c130 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1c140 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
1c150 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b only during.** [
1c160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
1c170 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
1c180 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 ts. Authorizati
1c190 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 on is not.** per
1c1a0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 formed during st
1c1b0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 atement evaluati
1c1c0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 on in [sqlite3_s
1c1d0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a tep()], unless.*
1c1e0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 * as stated in t
1c1f0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
1c200 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 graph, sqlite3_s
1c210 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a tep() invokes.**
1c220 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1c230 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 _v2() to reprepa
1c240 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 re a statement a
1c250 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 fter a schema ch
1c260 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ange..*/.SQLITE_
1c270 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1c280 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a set_authorizer(.
1c290 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e sqlite3*,. in
1c2a0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a t (*xAuth)(void*
1c2b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a ,int,const char*
1c2c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
1c2d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
1c2e0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 har*),. void *p
1c2f0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a UserData.);../*.
1c300 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
1c310 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 horizer Return C
1c320 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b odes.**.** The [
1c330 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1c340 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
1c350 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e zer callback fun
1c360 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 ction] must.** r
1c370 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 eturn either [SQ
1c380 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 LITE_OK] or one
1c390 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e of these two con
1c3a0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a stants in order.
1c3b0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c ** to signal SQL
1c3c0 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e ite whether or n
1c3d0 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 ot the action is
1c3e0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 permitted. See
1c3f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1c400 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1c410 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 | authorizer doc
1c420 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 umentation] for
1c430 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
1c440 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
1c450 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 Note that SQLIT
1c460 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f E_IGNORE is also
1c470 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 used as a [SQLI
1c480 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 TE_ROLLBACK | re
1c490 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 turn code].** fr
1c4a0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
1c4b0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 vtab_on_conflict
1c4c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
1c4d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1c4e0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 _DENY 1 /* A
1c4f0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
1c500 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 tement with an e
1c510 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
1c520 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 SQLITE_IGNORE 2
1c530 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 /* Don't allow
1c540 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e access, but don
1c550 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 't generate an e
1c560 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 rror */../*.** C
1c570 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
1c580 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 zer Action Codes
1c590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
1c5a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1c5b0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 er()] interface
1c5c0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
1c5d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a back function.**
1c5e0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 that is invoked
1c5f0 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 to authorize ce
1c600 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d rtain SQL statem
1c610 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 ent actions. Th
1c620 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 e.** second para
1c630 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c meter to the cal
1c640 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
1c650 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 ger code that sp
1c660 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 ecifies.** what
1c670 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 action is being
1c680 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
1c690 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 se are the integ
1c6a0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 er action codes
1c6b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 that.** the auth
1c6c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1c6d0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a may be passed..*
1c6e0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f *.** These actio
1c6f0 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 n code values si
1c700 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 gnify what kind
1c710 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 of operation is
1c720 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 to be.** authori
1c730 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e zed. The 3rd an
1c740 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 d 4th parameters
1c750 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
1c760 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 ation.** callbac
1c770 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 k function will
1c780 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 be parameters or
1c790 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 NULL depending
1c7a0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 on which of thes
1c7b0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 e.** codes is us
1c7c0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
1c7d0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 parameter. ^(T
1c7e0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
1c7f0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f to the.** autho
1c800 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1c810 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
1c820 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 e database ("mai
1c830 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 n", "temp",.** e
1c840 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 tc.) if applicab
1c850 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 le.)^ ^The 6th
1c860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1c870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1c880 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e back.** is the n
1c890 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 ame of the inner
1c8a0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 -most trigger or
1c8b0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 view that is re
1c8c0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a sponsible for.**
1c8d0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 the access atte
1c8e0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 mpt or NULL if t
1c8f0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d his access attem
1c900 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 pt is directly f
1c910 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c rom.** top-level
1c920 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a SQL code..*/./*
1c930 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1c940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1c950 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a ********** 3rd *
1c960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 *********** 4th
1c970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 ***********/.#de
1c980 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1c990 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 TE_INDEX
1c9a0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 1 /* Index N
1c9b0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
1c9c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1c9d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1c9e0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 E_TABLE
1c9f0 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 2 /* Table Na
1ca00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1ca10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1ca20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1ca30 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
1ca40 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 3 /* Index Nam
1ca50 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
1ca60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1ca70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1ca80 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 TEMP_TABLE 4
1ca90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1caa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1cab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1cac0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1cad0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 EMP_TRIGGER 5
1cae0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
1caf0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
1cb00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1cb10 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1cb20 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 MP_VIEW 6
1cb30 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
1cb40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1cb50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1cb60 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 QLITE_CREATE_TRI
1cb70 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 GGER 7
1cb80 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
1cb90 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1cba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1cbb0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 LITE_CREATE_VIEW
1cbc0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 8 /
1cbd0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
1cbe0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1cbf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1cc00 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ITE_DELETE
1cc10 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 9 /*
1cc20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1cc30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1cc40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1cc50 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 TE_DROP_INDEX
1cc60 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 10 /*
1cc70 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
1cc80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1cc90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1cca0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 E_DROP_TABLE
1ccb0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 11 /* T
1ccc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1ccd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1cce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ccf0 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 _DROP_TEMP_INDEX
1cd00 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 12 /* In
1cd10 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
1cd20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1cd30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1cd40 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 DROP_TEMP_TABLE
1cd50 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 13 /* Tab
1cd60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1cd70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1cd80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1cd90 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ROP_TEMP_TRIGGER
1cda0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 14 /* Trig
1cdb0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
1cdc0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1cdd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1cde0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 OP_TEMP_VIEW
1cdf0 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 15 /* View
1ce00 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1ce10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1ce20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1ce30 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 P_TRIGGER
1ce40 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 16 /* Trigge
1ce50 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
1ce60 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1ce70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1ce80 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
1ce90 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 17 /* View Na
1cea0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
1ceb0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1cec0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 ine SQLITE_INSER
1ced0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
1cee0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 18 /* Table Na
1cef0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1cf00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1cf10 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 ne SQLITE_PRAGMA
1cf20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
1cf30 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 9 /* Pragma Na
1cf40 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f me 1st arg o
1cf50 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e r NULL */.#defin
1cf60 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 e SQLITE_READ
1cf70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
1cf80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1cf90 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
1cfa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
1cfb0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 SQLITE_SELECT
1cfc0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 21
1cfd0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
1cfe0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1cff0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1d000 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 SQLITE_TRANSACTI
1d010 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 ON 22
1d020 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
1d030 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1d040 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1d050 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 QLITE_UPDATE
1d060 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 23
1d070 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1d080 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
1d090 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1d0a0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 LITE_ATTACH
1d0b0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 24 /
1d0c0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 * Filename
1d0d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1d0e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1d0f0 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 ITE_DETACH
1d100 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 25 /*
1d110 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
1d120 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1d130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1d140 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 TE_ALTER_TABLE
1d150 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 26 /*
1d160 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
1d170 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1d180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1d190 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 E_REINDEX
1d1a0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 27 /* I
1d1b0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e ndex Name N
1d1c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1d1d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1d1e0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 _ANALYZE
1d1f0 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 28 /* Ta
1d200 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1d210 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1d220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1d230 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 CREATE_VTABLE
1d240 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 29 /* Tab
1d250 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
1d260 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
1d270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1d280 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ROP_VTABLE
1d290 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 30 /* Tabl
1d2a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
1d2b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
1d2c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
1d2d0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 NCTION
1d2e0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 31 /* NULL
1d2f0 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 Funct
1d300 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 ion Name */.#d
1d310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 efine SQLITE_SAV
1d320 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 EPOINT
1d330 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 32 /* Operat
1d340 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f ion Savepo
1d350 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 int Name */.#de
1d360 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 fine SQLITE_COPY
1d370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1d380 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 0 /* No long
1d390 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a er used */../*.*
1d3a0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 * CAPI3REF: Trac
1d3b0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e ing And Profilin
1d3c0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a g Functions.**.*
1d3d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1d3e0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 register callba
1d3f0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ck functions tha
1d400 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f t can be used fo
1d410 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 r.** tracing and
1d420 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 profiling the e
1d430 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 xecution of SQL
1d440 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
1d450 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 * ^The callback
1d460 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
1d470 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 red by sqlite3_t
1d480 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 race() is invoke
1d490 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 d at.** various
1d4a0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 times when an SQ
1d4b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 L statement is b
1d4c0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c eing run by [sql
1d4d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
1d4e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 ^The sqlite3_tr
1d4f0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 ace() callback i
1d500 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 s invoked with a
1d510 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 UTF-8 rendering
1d520 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 of the.** SQL s
1d530 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 tatement text as
1d540 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 the statement f
1d550 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 irst begins exec
1d560 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 uting..** ^(Addi
1d570 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 tional sqlite3_t
1d580 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 race() callbacks
1d590 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
1d5a0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 as each triggere
1d5b0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 d subprogram is
1d5c0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 entered. The ca
1d5d0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 llbacks for trig
1d5e0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 gers.** contain
1d5f0 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d a UTF-8 SQL comm
1d600 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 ent that identif
1d610 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e ies the trigger.
1d620 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 )^.**.** ^The ca
1d630 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1d640 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
1d650 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 lite3_profile()
1d660 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 is invoked.** as
1d670 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d each SQL statem
1d680 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e ent finishes. ^
1d690 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c The profile call
1d6a0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a back contains.**
1d6b0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
1d6c0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 atement text and
1d6d0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 an estimate of
1d6e0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a wall-clock time.
1d6f0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 ** of how long t
1d700 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f hat statement to
1d710 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 ok to run. ^The
1d720 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 profile callbac
1d730 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 k.** time is in
1d740 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 units of nanosec
1d750 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 onds, however th
1d760 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d e current implem
1d770 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f entation.** is o
1d780 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d nly capable of m
1d790 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c illisecond resol
1d7a0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 ution so the six
1d7b0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 least significa
1d7c0 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 nt.** digits in
1d7d0 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 the time are mea
1d7e0 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 ningless. Futur
1d7f0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
1d800 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 Lite.** might pr
1d810 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 ovide greater re
1d820 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 solution on the
1d830 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 profiler callbac
1d840 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 k. The.** sqlit
1d850 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e e3_profile() fun
1d860 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 ction is conside
1d870 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c red experimental
1d880 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 and is.** subje
1d890 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 ct to change in
1d8a0 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 future versions
1d8b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 of SQLite..*/.SQ
1d8c0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 LITE_API void *s
1d8d0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
1d8e0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
1d8f0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
1d900 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
1d910 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
1d920 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
1d930 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 void *sqlite3_pr
1d940 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a ofile(sqlite3*,.
1d950 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c void(*xProfil
1d960 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
1d970 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e har*,sqlite3_uin
1d980 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t64), void*);../
1d990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 *.** CAPI3REF: Q
1d9a0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 uery Progress Ca
1d9b0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 llbacks.**.** ^T
1d9c0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 he sqlite3_progr
1d9d0 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c ess_handler(D,N,
1d9e0 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 X,P) interface c
1d9f0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 auses the callba
1da00 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 ck.** function X
1da10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 to be invoked p
1da20 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 eriodically duri
1da30 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 ng long running
1da40 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
1da50 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 ite3_exec()], [s
1da60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 qlite3_step()] a
1da70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f nd [sqlite3_get_
1da80 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 table()] for.**
1da90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1daa0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 ion D. An examp
1dab0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
1dac0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
1dad0 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
1dae0 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
1daf0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
1db00 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 * ^The parameter
1db10 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 P is passed thr
1db20 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 ough as the only
1db30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1db40 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 e .** callback f
1db50 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 unction X. ^The
1db60 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 parameter N is
1db70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a the number of .*
1db80 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 * [virtual machi
1db90 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d ne instructions]
1dba0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 that are evalua
1dbb0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 ted between succ
1dbc0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 essive.** invoca
1dbd0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c tions of the cal
1dbe0 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e lback X..**.** ^
1dbf0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 Only a single pr
1dc00 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d ogress handler m
1dc10 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 ay be defined at
1dc20 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a one time per.**
1dc30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1dc40 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 ction]; setting
1dc50 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 a new progress h
1dc60 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 andler cancels t
1dc70 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 he.** old one.
1dc80 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 ^Setting paramet
1dc90 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 er X to NULL dis
1dca0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 ables the progre
1dcb0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e ss handler..** ^
1dcc0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
1dcd0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 dler is also dis
1dce0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 abled by setting
1dcf0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 N to a value le
1dd00 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a ss.** than 1..**
1dd10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 .** ^If the prog
1dd20 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 ress callback re
1dd30 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
1dd40 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 the operation is
1dd50 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e .** interrupted.
1dd60 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 This feature c
1dd70 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d an be used to im
1dd80 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 plement a.** "Ca
1dd90 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 ncel" button on
1dda0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 a GUI progress d
1ddb0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a ialog box..**.**
1ddc0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 The progress ha
1ddd0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d ndler callback m
1dde0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
1ddf0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
1de00 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
1de10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1de20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
1de30 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
1de40 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 r..** Note that
1de50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1de60 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
1de70 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
1de80 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
1de90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1dea0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
1deb0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
1dec0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
1ded0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 aph..**.*/.SQLIT
1dee0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
1def0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
1df00 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
1df10 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 t, int(*)(void*)
1df20 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
1df30 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 CAPI3REF: Openi
1df40 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 ng A New Databas
1df50 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a e Connection.**.
1df60 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
1df70 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 es open an SQLit
1df80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
1df90 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 as specified by
1dfa0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the .** filename
1dfb0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 argument. ^The
1dfc0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
1dfd0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
1dfe0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a as UTF-8 for.**
1dff0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
1e000 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
1e010 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 _v2() and as UTF
1e020 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
1e030 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 e byte.** order
1e040 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
1e050 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 16(). ^(A [datab
1e060 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1e070 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c handle is usuall
1e080 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e y.** returned in
1e090 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 *ppDb, even if
1e0a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e an error occurs.
1e0b0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 The only excep
1e0c0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 tion is that.**
1e0d0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 if SQLite is una
1e0e0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
1e0f0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
1e100 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
1e110 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 ect,.** a NULL w
1e120 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 ill be written i
1e130 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 nto *ppDb instea
1e140 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 d of a pointer t
1e150 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a o the [sqlite3].
1e160 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 ** object.)^ ^(I
1e170 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 f the database i
1e180 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 s opened (and/or
1e190 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 created) succes
1e1a0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 sfully, then.**
1e1b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
1e1c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
1e1d0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
1e1e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
1e1f0 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 )^ ^The.** [sqli
1e200 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 te3_errmsg()] or
1e210 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1e220 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 16()] routines c
1e230 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 an be used to ob
1e240 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 tain.** an Engli
1e250 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 sh language desc
1e260 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 ription of the e
1e270 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 rror following a
1e280 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a failure of any.
1e290 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ** of the sqlite
1e2a0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 3_open() routine
1e2b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 s..**.** ^The de
1e2c0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 fault encoding f
1e2d0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 or the database
1e2e0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 will be UTF-8 if
1e2f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
1e300 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 () or sqlite3_op
1e310 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 en_v2() is calle
1e320 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 d and.** UTF-16
1e330 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
1e340 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 te order if sqli
1e350 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 te3_open16() is
1e360 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 used..**.** Whet
1e370 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 her or not an er
1e380 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 ror occurs when
1e390 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 it is opened, re
1e3a0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 sources.** assoc
1e3b0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b iated with the [
1e3c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1e3d0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 ion] handle shou
1e3e0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 ld be released b
1e3f0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 y.** passing it
1e400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to [sqlite3_clos
1e410 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 e()] when it is
1e420 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 no longer requir
1e430 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
1e440 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
1e450 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 interface works
1e460 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 like sqlite3_ope
1e470 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 n().** except th
1e480 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 at it accepts tw
1e490 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 o additional par
1e4a0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 ameters for addi
1e4b0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a tional control.*
1e4c0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 * over the new d
1e4d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1e4e0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 on. ^(The flags
1e4f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
1e500 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1e510 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 () can take one
1e520 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 of.** the follow
1e530 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 ing three values
1e540 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d , optionally com
1e550 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a bined with the .
1e560 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
1e570 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 NOMUTEX], [SQLIT
1e580 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
1e590 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
1e5a0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a SHAREDCACHE],.**
1e5b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
1e5c0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 IVATECACHE], and
1e5d0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e /or [SQLITE_OPEN
1e5e0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a _URI] flags:)^.*
1e5f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c *.** <dl>.** ^(<
1e600 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
1e610 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a READONLY]</dt>.*
1e620 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
1e630 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 se is opened in
1e640 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 read-only mode.
1e650 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
1e660 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 does not.** alr
1e670 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 eady exist, an e
1e680 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
1e690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
1e6a0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
1e6b0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 N_READWRITE]</dt
1e6c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
1e6d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1e6e0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
1e6f0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 writing if possi
1e700 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a ble, or reading.
1e710 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 ** only if the f
1e720 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f ile is write pro
1e730 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 tected by the op
1e740 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
1e750 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 In either.** ca
1e760 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
1e770 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 must already exi
1e780 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e st, otherwise an
1e790 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
1e7a0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
1e7b0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
1e7c0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
1e7d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
1e7e0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 EATE]</dt>.** <d
1e7f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
1e800 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
1e810 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
1e820 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 , and is created
1e830 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e if.** it does n
1e840 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ot already exist
1e850 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 . This is the be
1e860 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 havior that is a
1e870 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a lways used for.*
1e880 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
1e890 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
1e8a0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a n16().</dd>)^.**
1e8b0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </dl>.**.** If
1e8c0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
1e8d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
1e8e0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e n_v2() is not on
1e8f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 e of the.** comb
1e900 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 inations shown a
1e910 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 bove optionally
1e920 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 combined with ot
1e930 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f her.** [SQLITE_O
1e940 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 PEN_READONLY | S
1e950 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 QLITE_OPEN_* bit
1e960 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 s].** then the b
1e970 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
1e980 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ined..**.** ^If
1e990 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
1e9a0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 _NOMUTEX] flag i
1e9b0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 s set, then the
1e9c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1e9d0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 ion.** opens in
1e9e0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 the multi-thread
1e9f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
1ea00 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ] as long as the
1ea10 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a single-thread.*
1ea20 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 * mode has not b
1ea30 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 een set at compi
1ea40 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
1ea50 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a -time. ^If the.
1ea60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
1ea70 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 FULLMUTEX] flag
1ea80 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 is set then the
1ea90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1eaa0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 ion opens.** in
1eab0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
1eac0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
1ead0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 unless single-th
1eae0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 read was.** prev
1eaf0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 iously selected
1eb00 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
1eb10 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a or start-time..*
1eb20 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f * ^The [SQLITE_O
1eb30 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
1eb40 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
1eb50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1eb60 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c tion to be.** el
1eb70 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 igible to use [s
1eb80 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
1eb90 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ], regardless of
1eba0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1ebb0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 shared.** cache
1ebc0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 is enabled using
1ebd0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
1ebe0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d _shared_cache()]
1ebf0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 . ^The.** [SQLI
1ec00 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
1ec10 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 ACHE] flag cause
1ec20 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
1ec30 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 onnection to not
1ec40 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 .** participate
1ec50 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 in [shared cache
1ec60 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 mode] even if i
1ec70 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a t is enabled..**
1ec80 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
1ec90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1eca0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
1ecb0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
1ecc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
1ecd0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
1ece0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 efines the opera
1ecf0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
1ed00 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 rface that.** th
1ed10 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
1ed20 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 onnection should
1ed30 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 use. ^If the f
1ed40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
1ed50 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 is.** a NULL poi
1ed60 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 nter then the de
1ed70 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
1ed80 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 fs] object is us
1ed90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
1eda0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a e filename is ":
1edb0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 memory:", then a
1edc0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 private, tempor
1edd0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 ary in-memory da
1ede0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 tabase.** is cre
1edf0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e ated for the con
1ee00 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 nection. ^This
1ee10 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
1ee20 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 se will vanish w
1ee30 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 hen.** the datab
1ee40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
1ee50 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 s closed. Futur
1ee60 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
1ee70 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 Lite might.** ma
1ee80 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 ke use of additi
1ee90 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c onal special fil
1eea0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 enames that begi
1eeb0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 n with the ":" c
1eec0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 haracter..** It
1eed0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
1eee0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 hat when a datab
1eef0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 ase filename act
1ef00 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e ually does begin
1ef10 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 with.** a ":" c
1ef20 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f haracter you sho
1ef30 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 uld prefix the f
1ef40 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 ilename with a p
1ef50 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a athname such as.
1ef60 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 ** "./" to avoid
1ef70 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a ambiguity..**.*
1ef80 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 * ^If the filena
1ef90 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 me is an empty s
1efa0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 tring, then a pr
1efb0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
1efc0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 .** on-disk data
1efd0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
1efe0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 ated. ^This pri
1eff0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 vate database wi
1f000 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 ll be.** automat
1f010 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 ically deleted a
1f020 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 s soon as the da
1f030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1f040 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a n is closed..**.
1f050 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d ** [[URI filenam
1f060 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 es in sqlite3_op
1f070 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 en()]] <h3>URI F
1f080 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a ilenames</h3>.**
1f090 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c .** ^If [URI fil
1f0a0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 ename] interpret
1f0b0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
1f0c0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 , and the filena
1f0d0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 me argument.** b
1f0e0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 egins with "file
1f0f0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c :", then the fil
1f100 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 ename is interpr
1f110 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e eted as a URI. ^
1f120 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 URI.** filename
1f130 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
1f140 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 s enabled if the
1f150 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
1f160 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 I] flag is.** se
1f170 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 t in the fourth
1f180 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
1f190 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f te3_open_v2(), o
1f1a0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 r if it has.** b
1f1b0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 een enabled glob
1f1c0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b ally using the [
1f1d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
1f1e0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 I] option with t
1f1f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 he.** [sqlite3_c
1f200 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 onfig()] method
1f210 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 or by the [SQLIT
1f220 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 E_USE_URI] compi
1f230 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a le-time option..
1f240 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 ** As of SQLite
1f250 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 version 3.7.7, U
1f260 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 RI filename inte
1f270 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 rpretation is tu
1f280 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 rned off.** by d
1f290 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 efault, but futu
1f2a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
1f2b0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 QLite might enab
1f2c0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a le URI filename.
1f2d0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f ** interpretatio
1f2e0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 n by default. S
1f2f0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d ee "[URI filenam
1f300 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f es]" for additio
1f310 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
1f320 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 on..**.** URI fi
1f330 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 lenames are pars
1f340 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 ed according to
1f350 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 RFC 3986. ^If th
1f360 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 e URI contains a
1f370 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 n.** authority,
1f380 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 then it must be
1f390 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 either an empty
1f3a0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 string or the st
1f3b0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 ring .** "localh
1f3c0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 ost". ^If the au
1f3d0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 thority is not a
1f3e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f n empty string o
1f3f0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 r "localhost", a
1f400 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 n .** error is r
1f410 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 eturned to the c
1f420 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 aller. ^The frag
1f430 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f ment component o
1f440 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 f a URI, if .**
1f450 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f present, is igno
1f460 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 red..**.** ^SQLi
1f470 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 te uses the path
1f480 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 component of th
1f490 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d e URI as the nam
1f4a0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 e of the disk fi
1f4b0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 le.** which cont
1f4c0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 ains the databas
1f4d0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 e. ^If the path
1f4e0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f begins with a '/
1f4f0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a ' character, .**
1f500 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 then it is inte
1f510 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 rpreted as an ab
1f520 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 solute path. ^If
1f530 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e the path does n
1f540 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 ot begin .** wit
1f550 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 h a '/' (meaning
1f560 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
1f570 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f ity section is o
1f580 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
1f590 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 URI).** then the
1f5a0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 path is interpr
1f5b0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 eted as a relati
1f5c0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e ve path. .** ^On
1f5d0 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 windows, the fi
1f5e0 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 rst component of
1f5f0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 an absolute pat
1f600 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 h .** is a drive
1f610 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 specification (
1f620 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a e.g. "C:")..**.*
1f630 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 * [[core URI que
1f640 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a ry parameters]].
1f650 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d ** The query com
1f660 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 ponent of a URI
1f670 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 may contain para
1f680 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 meters that are
1f690 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 interpreted.** e
1f6a0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 ither by SQLite
1f6b0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 itself, or by a
1f6c0 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 [VFS | custom VF
1f6d0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
1f6e0 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 ]..** SQLite int
1f6f0 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c erprets the foll
1f700 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 owing three quer
1f710 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a y parameters:.**
1f720 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c .** <ul>.** <l
1f730 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e i> <b>vfs</b>: ^
1f740 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 The "vfs" parame
1f750 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 ter may be used
1f760 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e to specify the n
1f770 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 ame of.** a
1f780 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 VFS object that
1f790 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 provides the ope
1f7a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e rating system in
1f7b0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f terface that sho
1f7c0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 uld.** be us
1f7d0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ed to access the
1f7e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f database file o
1f7f0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 n disk. ^If this
1f800 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 option is set t
1f810 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 o.** an empt
1f820 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 y string the def
1f830 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 ault VFS object
1f840 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 is used. ^Specif
1f850 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a ying an unknown.
1f860 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e ** VFS is an
1f870 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 error. ^If sqli
1f880 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1f890 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 used and the vf
1f8a0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 s option is.**
1f8b0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e present, then
1f8c0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 the VFS specifi
1f8d0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e ed by the option
1f8e0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 takes precedenc
1f8f0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 e over.** th
1f900 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 e value passed a
1f910 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 s the fourth par
1f920 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1f930 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
1f940 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 ** <li> <b>mod
1f950 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 e</b>: ^(The mod
1f960 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
1f970 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
1f980 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 "ro", "rw",.**
1f990 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d "rwc", or "m
1f9a0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 emory". Attempti
1f9b0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 ng to set it to
1f9c0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 any other value
1f9d0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 is.** an err
1f9e0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 or)^. .** ^I
1f9f0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 f "ro" is specif
1fa00 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 ied, then the da
1fa10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1fa20 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a for read-only .
1fa30 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a ** access, j
1fa40 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 ust as if the [S
1fa50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
1fa60 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 NLY] flag had be
1fa70 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a en set in the .*
1fa80 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 * third argu
1fa90 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
1faa0 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 prepare_v2(). ^I
1fab0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
1fac0 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 n is set to .**
1fad0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 "rw", then t
1fae0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
1faf0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 pened for read-w
1fb00 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 rite (but not cr
1fb10 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 eate) .** ac
1fb20 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 cess, as if SQLI
1fb30 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
1fb40 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 E (but not SQLIT
1fb50 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 E_OPEN_CREATE) h
1fb60 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 ad .** been
1fb70 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 set. ^Value "rwc
1fb80 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
1fb90 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 to setting both
1fba0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
1fbb0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e PEN_READWRITE an
1fbc0 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 d SQLITE_OPEN_CR
1fbd0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d EATE. ^If the m
1fbe0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ode option is.**
1fbf0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d set to "mem
1fc00 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 ory" then a pure
1fc10 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 [in-memory data
1fc20 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 base] that never
1fc30 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 reads.** or
1fc40 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 writes from dis
1fc50 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 k is used. ^It i
1fc60 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 s an error to sp
1fc70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f ecify a value fo
1fc80 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 r.** the mod
1fc90 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
1fca0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 is less restric
1fcb0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 tive than that s
1fcc0 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
1fcd0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 the flags pas
1fce0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 sed in the third
1fcf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1fd00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
1fd10 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
1fd20 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 >cache</b>: ^The
1fd30 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
1fd40 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
1fd50 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f ither "shared" o
1fd60 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 r.** "privat
1fd70 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 e". ^Setting it
1fd80 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 to "shared" is e
1fd90 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
1fda0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 ting the.**
1fdb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
1fdc0 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 EDCACHE bit in t
1fdd0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
1fde0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 t passed to.**
1fdf0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f sqlite3_open_
1fe00 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 v2(). ^Setting t
1fe10 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
1fe20 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 er to "private"
1fe30 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 is .** equiv
1fe40 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
1fe50 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e the SQLITE_OPEN
1fe60 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 _PRIVATECACHE bi
1fe70 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 t..** ^If sq
1fe80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
1fe90 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 is used and the
1fea0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 "cache" paramete
1feb0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a r is present in.
1fec0 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c ** a URI fil
1fed0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 ename, its value
1fee0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 overrides any b
1fef0 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74 ehaviour request
1ff00 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a ed by setting.**
1ff10 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
1ff20 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 _PRIVATECACHE or
1ff30 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
1ff40 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a REDCACHE flag..*
1ff50 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 * </ul>.**.** ^S
1ff60 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b pecifying an unk
1ff70 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 nown parameter i
1ff80 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 n the query comp
1ff90 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 onent of a URI i
1ffa0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f s not an.** erro
1ffb0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 r. Future versi
1ffc0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
1ffd0 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 ght understand a
1ffe0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a dditional query.
1fff0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ** parameters.
20000 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 See "[query para
20010 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 meters with spec
20020 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 ial meaning to S
20030 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 QLite]" for.** a
20040 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
20050 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 ation..**.** [[U
20060 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
20070 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 ples]] <h3>URI f
20080 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 ilename examples
20090 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 </h3>.**.** <tab
200a0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c le border="1" al
200b0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 ign=center cellp
200c0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 adding=5>.** <tr
200d0 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 ><th> URI filena
200e0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 mes <th> Results
200f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
20100 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a e:data.db <td> .
20110 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
20120 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e the file "data.
20130 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 db" in the curre
20140 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a nt directory..**
20150 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
20160 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
20170 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 b<br>.**
20180 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 file:///home/f
20190 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
201a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 .** fi
201b0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 le://localhost/h
201c0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
201d0 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 <br> <td> .**
201e0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 Open the
201f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 database file "
20200 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
20210 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e db"..** <tr><td>
20220 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 file://darkstar
20230 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
20240 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
20250 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 An error. "
20260 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 darkstar" is not
20270 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 a recognized au
20280 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e thority..** <tr>
20290 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 <td style="white
202a0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 -space:nowrap">
202b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
202c0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 e:///C:/Document
202d0 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e s%20and%20Settin
202e0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f gs/fred/Desktop/
202f0 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c data.db.** <
20300 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 td> Windows only
20310 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 : Open the file
20320 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 "data.db" on fre
20330 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 d's desktop on d
20340 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 rive.**
20350 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 C:. Note that t
20360 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 he %20 escaping
20370 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 in this example
20380 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 is not strictly
20390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 .** nec
203a0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 essary - space c
203b0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 haracters can be
203c0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a used literally.
203d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 ** in U
203e0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a RI filenames..**
203f0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 <tr><td> file:d
20400 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 ata.db?mode=ro&c
20410 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 ache=private <td
20420 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
20430 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 pen file "data.d
20440 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
20450 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 t directory for
20460 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 read-only access
20470 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 ..** Re
20480 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
20490 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
204a0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 d-cache mode is
204b0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 enabled by.**
204c0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 default,
204d0 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 use a private ca
204e0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e che..** <tr><td>
204f0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
20500 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 /data.db?vfs=uni
20510 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a x-nolock <td>.**
20520 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
20530 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
20540 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 data.db". Use th
20550 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 e special VFS "u
20560 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 nix-nolock"..**
20570 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
20580 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f ta.db?mode=reado
20590 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 nly <td> .**
205a0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 An error.
205b0 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f "readonly" is no
205c0 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e t a valid option
205d0 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 for the "mode"
205e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f parameter..** </
205f0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 table>.**.** ^UR
20600 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 I hexadecimal es
20610 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 cape sequences (
20620 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 %HH) are support
20630 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 ed within the pa
20640 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 th and.** query
20650 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 components of a
20660 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d URI. A hexadecim
20670 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
20680 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 ce consists of a
20690 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e .** percent sign
206a0 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 - "%" - followe
206b0 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f d by exactly two
206c0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 hexadecimal dig
206d0 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 its .** specifyi
206e0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 ng an octet valu
206f0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 e. ^Before the p
20700 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d ath or query com
20710 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 ponents of a.**
20720 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 URI filename are
20730 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 interpreted, th
20740 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 ey are encoded u
20750 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 sing UTF-8 and a
20760 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d ll .** hexadecim
20770 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
20780 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 ces replaced by
20790 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f a single byte co
207a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 ntaining the.**
207b0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 corresponding oc
207c0 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f tet. If this pro
207d0 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 cess generates a
207e0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 n invalid UTF-8
207f0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 encoding,.** the
20800 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
20810 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 efined..**.** <b
20820 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
20830 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
20840 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 encoding used f
20850 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 or the filename
20860 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 argument.** of s
20870 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
20880 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
20890 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 2() must be UTF-
208a0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 8, not whatever.
208b0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 ** codepage is c
208c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
208d0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
208e0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
208f0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 ional.** charact
20900 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ers must be conv
20910 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 erted to UTF-8 p
20920 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
20930 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c them into.** sql
20940 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
20950 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
20960 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
20970 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 to Windows Runti
20980 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 me users:</b> T
20990 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 he temporary dir
209a0 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 ectory must be s
209b0 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 et.** prior to c
209c0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f alling sqlite3_o
209d0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
209e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 _open_v2(). Oth
209f0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a erwise, various.
20a00 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 ** features that
20a10 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 require the use
20a20 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 of temporary fi
20a30 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a les may fail..**
20a40 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
20a50 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
20a60 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 ctory].*/.SQLITE
20a70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
20a80 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 _open(. const c
20a90 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 har *filename,
20aa0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
20ab0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f ename (UTF-8) */
20ac0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
20ad0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
20ae0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
20af0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 dle */.);.SQLITE
20b00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
20b10 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 _open16(. const
20b20 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c void *filename,
20b30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 /* Database f
20b40 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 ilename (UTF-16)
20b50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
20b60 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
20b70 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
20b80 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c handle */.);.SQL
20b90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
20ba0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 te3_open_v2(. c
20bb0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
20bc0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
20bd0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
20be0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
20bf0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 **ppDb,
20c00 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
20c10 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 db handle */. i
20c20 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 nt flags,
20c30 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 /* Flags
20c40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
20c50 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 *zVfs /*
20c60 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 Name of VFS modu
20c70 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a le to use */.);.
20c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20c90 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 Obtain Values F
20ca0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 or URI Parameter
20cb0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 s.**.** These ar
20cc0 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e e utility routin
20cd0 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 es, useful to VF
20ce0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
20cf0 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a s, that check.**
20d00 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 to see if a dat
20d10 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 abase file was a
20d20 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 URI that contai
20d30 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 ned a specific q
20d40 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 uery .** paramet
20d50 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 er, and if so ob
20d60 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 tains the value
20d70 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 of that query pa
20d80 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
20d90 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 f F is the datab
20da0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 ase filename poi
20db0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f nter passed into
20dc0 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 the xOpen() met
20dd0 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 hod of .** a VFS
20de0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
20df0 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 when the flags p
20e00 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
20e10 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a n() has one or .
20e20 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b ** more of the [
20e30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
20e40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e or [SQLITE_OPEN
20e50 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 _MAIN_DB] bits s
20e60 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 et and.** P is t
20e70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 he name of the q
20e80 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 uery parameter,
20e90 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f then.** sqlite3_
20ea0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c uri_parameter(F,
20eb0 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 P) returns the v
20ec0 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a alue of the P.**
20ed0 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 parameter if it
20ee0 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c exists or a NUL
20ef0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 L pointer if P d
20f00 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 oes not appear a
20f10 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 s a .** query pa
20f20 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 rameter on F. I
20f30 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 f P is a query p
20f40 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a arameter of F.**
20f50 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 has no explicit
20f60 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c value, then sql
20f70 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
20f80 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a er(F,P) returns.
20f90 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
20fa0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e an empty string.
20fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
20fc0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
20fd0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 ,P,B) routine as
20fe0 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 sumes that P is
20ff0 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 a boolean.** par
21000 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 ameter and retur
21010 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 ns true (1) or f
21020 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 alse (0) accordi
21030 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a ng to the value.
21040 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 ** of P. The sq
21050 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
21060 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
21070 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 returns true (1
21080 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ) if the.** valu
21090 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d e of query param
210a0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
210b0 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 "yes", "true",
210c0 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a or "on" in any.*
210d0 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 * case or if the
210e0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 value begins wi
210f0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 th a non-zero nu
21100 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 mber. The .** s
21110 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
21120 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e an(F,P,B) routin
21130 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 es returns false
21140 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 (0) if the valu
21150 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 e of.** query pa
21160 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
21170 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 of "no", "false
21180 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 ", or "off" in a
21190 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 ny case or.** if
211a0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e the value begin
211b0 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 s with a numeric
211c0 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 zero. If P is
211d0 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 not a query.** p
211e0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 arameter on F or
211f0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 if the value of
21200 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d P is does not m
21210 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a atch any of the.
21220 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 ** above, then s
21230 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
21240 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e an(F,P,B) return
21250 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 s (B!=0)..**.**
21260 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
21270 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 int64(F,P,D) rou
21280 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 tine converts th
21290 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 e value of P int
212a0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 o a.** 64-bit si
212b0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 gned integer and
212c0 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e returns that in
212d0 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 teger, or D if P
212e0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 does not.** exi
212f0 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 st. If the valu
21300 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 e of P is someth
21310 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 ing other than a
21320 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a n integer, then.
21330 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 ** zero is retur
21340 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 ned..** .** If F
21350 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
21360 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 er, then sqlite3
21370 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 _uri_parameter(F
21380 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ,P) returns NULL
21390 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
213a0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
213b0 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 B) returns B. I
213c0 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c f F is not a NUL
213d0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a L pointer and.**
213e0 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 is not a databa
213f0 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 se file pathname
21400 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 pointer that SQ
21410 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f Lite passed into
21420 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 the xOpen.** VF
21430 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 S method, then t
21440 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 he behavior of t
21450 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
21460 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
21470 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 bably.** undesir
21480 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f able..*/.SQLITE_
21490 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
214a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
214b0 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 meter(const char
214c0 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e *zFilename, con
214d0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 st char *zParam)
214e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
214f0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
21500 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 lean(const char
21510 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 *zFile, const ch
21520 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 ar *zParam, int
21530 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 bDefault);.SQLIT
21540 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
21550 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f t64 sqlite3_uri_
21560 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 int64(const char
21570 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 *, const char*,
21580 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
21590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
215a0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e : Error Codes An
215b0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a d Messages.**.**
215c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 ^The sqlite3_er
215d0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 rcode() interfac
215e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
215f0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f meric [result co
21600 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
21610 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
21620 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 for the most re
21630 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 cent failed sqli
21640 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a te3_* API call.*
21650 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
21660 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f h a [database co
21670 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 nnection]. If a
21680 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 prior API call f
21690 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 ailed.** but the
216a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 most recent API
216b0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c call succeeded,
216c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
216d0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 e from.** sqlite
216e0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 3_errcode() is u
216f0 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 ndefined. ^The
21700 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
21710 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e _errcode().** in
21720 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 terface is the s
21730 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 ame except that
21740 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
21750 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e s the .** [exten
21760 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
21770 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e even when exten
21780 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
21790 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 are.** disabled
217a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
217b0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e ite3_errmsg() an
217c0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 d sqlite3_errmsg
217d0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 16() return Engl
217e0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 ish-language.**
217f0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 text that descri
21800 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 bes the error, a
21810 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
21820 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 r UTF-16 respect
21830 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f ively..** ^(Memo
21840 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
21850 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
21860 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
21870 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 nternally..** Th
21880 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
21890 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 es not need to w
218a0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 orry about freei
218b0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a ng the result..*
218c0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 * However, the e
218d0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 rror string migh
218e0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e t be overwritten
218f0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 or deallocated
21900 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 by.** subsequent
21910 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 calls to other
21920 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
21930 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a functions.)^.**
21940 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 .** When the ser
21950 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
21960 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 ng mode] is in u
21970 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 se, it might be
21980 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 the.** case that
21990 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 a second error
219a0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 occurs on a sepa
219b0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 rate thread in b
219c0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 etween.** the ti
219d0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 me of the first
219e0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 error and the ca
219f0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 ll to these inte
21a00 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 rfaces..** When
21a10 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 that happens, th
21a20 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 e second error w
21a30 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 ill be reported
21a40 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 since these.** i
21a50 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 nterfaces always
21a60 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 report the most
21a70 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 recent result.
21a80 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 To avoid.** thi
21a90 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 s, each thread c
21aa0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 an obtain exclus
21ab0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b ive use of the [
21ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
21ad0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 ion] D.** by inv
21ae0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
21af0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c utex_enter]([sql
21b00 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
21b10 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e )) before beginn
21b20 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 ing.** to use D
21b30 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 and invoking [sq
21b40 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
21b50 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d e]([sqlite3_db_m
21b60 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a utex](D)) after.
21b70 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 ** all calls to
21b80 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c the interfaces l
21b90 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 isted here are c
21ba0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ompleted..**.**
21bb0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 If an interface
21bc0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 fails with SQLIT
21bd0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d E_MISUSE, that m
21be0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 eans the interfa
21bf0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 ce.** was invoke
21c00 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 d incorrectly by
21c10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
21c20 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c . In that case,
21c30 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f the.** error co
21c40 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d de and message m
21c50 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 ay or may not be
21c60 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f set..*/.SQLITE_
21c70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
21c80 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
21c90 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *db);.SQLITE_API
21ca0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 int sqlite3_ext
21cb0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 ended_errcode(sq
21cc0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
21cd0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
21ce0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r *sqlite3_errms
21cf0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c g(sqlite3*);.SQL
21d00 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
21d10 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d id *sqlite3_errm
21d20 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a sg16(sqlite3*);.
21d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
21d40 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f SQL Statement O
21d50 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
21d60 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
21d70 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
21d80 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
21d90 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
21da0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
21db0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
21dc0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
21dd0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
21de0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e is variously kn
21df0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 own as a "prepar
21e00 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 ed statement" or
21e10 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a.** "compiled
21e20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
21e30 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
21e40 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a tatement"..**.**
21e50 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 The life of a s
21e60 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
21e70 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c goes something l
21e80 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
21e90 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 <ol>.** <li> Cre
21ea0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 ate the object u
21eb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
21ec0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 epare_v2()] or a
21ed0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 related.**
21ee0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c function..** <l
21ef0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
21f00 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 o [host paramete
21f10 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 rs] using the sq
21f20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
21f30 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 * interface
21f40 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 s..** <li> Run t
21f50 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e he SQL by callin
21f60 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
21f70 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 )] one or more t
21f80 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 imes..** <li> Re
21f90 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e set the statemen
21fa0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
21fb0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
21fc0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
21fd0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
21fe0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
21ff0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
22000 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
22010 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
22020 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
22030 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 </ol>.**.** Ref
22040 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 er to documentat
22050 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
22060 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 l methods above
22070 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
22080 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
22090 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
220a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 sqlite3_stmt sq
220b0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a lite3_stmt;../*.
220c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
220d0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a -time Limits.**.
220e0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 ** ^(This interf
220f0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
22100 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
22110 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
22120 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
22130 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
22140 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
22150 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
22160 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
22170 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22180 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
22190 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
221a0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
221b0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
221c0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
221d0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
221e0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
221f0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
22200 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
22210 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
22220 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
22230 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
22240 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
22250 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a onstruct.)^.**.*
22260 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 * ^If the new li
22270 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
22280 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
22290 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
222a0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 ..** ^(For each
222b0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 limit category S
222c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e QLITE_LIMIT_<i>N
222d0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 AME</i> there is
222e0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c a .** [limits |
222f0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
22300 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d d].** set at com
22310 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 pile-time by a C
22320 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
22330 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c cro called.** [l
22340 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d imits | SQLITE_M
22350 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e AX_<i>NAME</i>].
22360 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 .** (The "_LIMIT
22370 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 _" in the name i
22380 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d s changed to "_M
22390 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 AX_".))^.** ^Att
223a0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 empts to increas
223b0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 e a limit above
223c0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 its hard upper b
223d0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 ound are.** sile
223e0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 ntly truncated t
223f0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 o the hard upper
22400 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 bound..**.** ^R
22410 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
22420 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
22430 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 limit was change
22440 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 d, the .** [sqli
22450 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 te3_limit()] int
22460 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
22470 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
22480 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 f the limit..**
22490 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 ^Hence, to find
224a0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
224b0 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 e of a limit wit
224c0 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 hout changing it
224d0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f ,.** simply invo
224e0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ke this interfac
224f0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 e with the third
22500 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 parameter set t
22510 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d o -1..**.** Run-
22520 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 time limits are
22530 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
22540 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 in applications
22550 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 that manage.**
22560 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 both their own i
22570 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
22580 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 and also databa
22590 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ses that are con
225a0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e trolled.** by un
225b0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c trusted external
225c0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 sources. An ex
225d0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f ample applicatio
225e0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 n might be a.**
225f0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 web browser that
22600 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
22610 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
22620 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
22630 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
22640 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
22650 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
22660 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
22670 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
22680 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
22690 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
226a0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
226b0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
226c0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
226d0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
226e0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
226f0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
22700 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
22710 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
22720 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
22730 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
22740 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
22750 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
22760 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
22770 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
22780 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
22790 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
227a0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
227b0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
227c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
227d0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
227e0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
227f0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
22800 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
22810 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
22820 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
22830 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
22840 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
22850 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
22860 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
22870 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 eases..*/.SQLITE
22880 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
22890 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c _limit(sqlite3*,
228a0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 int id, int new
228b0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Val);../*.** CAP
228c0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
228d0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 Limit Categories
228e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c .** KEYWORDS: {l
228f0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b imit category} {
22900 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 *limit categorie
22910 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 s}.**.** These c
22920 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
22930 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 various performa
22940 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 nce limits.** th
22950 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 at can be lowere
22960 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 d at run-time us
22970 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
22980 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 it()]..** The sy
22990 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 nopsis of the me
229a0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
229b0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 rious limits is
229c0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 shown below..**
229d0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 Additional infor
229e0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 mation is availa
229f0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c ble at [limits |
22a00 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 Limits in SQLit
22a10 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a e]..**.** <dl>.*
22a20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
22a30 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e _LENGTH]] ^(<dt>
22a40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
22a50 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
22a60 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 The maximum size
22a70 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f of any string o
22a80 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 r BLOB or table
22a90 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 row, in bytes.<d
22aa0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
22ab0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
22ac0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c NGTH]] ^(<dt>SQL
22ad0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
22ae0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
22af0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
22b00 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 gth of an SQL st
22b10 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 atement, in byte
22b20 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
22b30 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
22b40 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 OLUMN]] ^(<dt>SQ
22b50 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
22b60 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 N</dt>.** <dd>Th
22b70 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
22b80 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
22b90 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f table definitio
22ba0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 n or in the.** r
22bb0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
22bc0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d SELECT] or the m
22bd0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
22be0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 columns in an i
22bf0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e ndex.** or in an
22c00 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f ORDER BY or GRO
22c10 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 UP BY clause.</d
22c20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
22c30 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
22c40 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c EPTH]] ^(<dt>SQL
22c50 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
22c60 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
22c70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
22c80 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 th of the parse
22c90 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 tree on any expr
22ca0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a ession.</dd>)^.*
22cb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
22cc0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
22cd0 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ECT]] ^(<dt>SQLI
22ce0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
22cf0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a D_SELECT</dt>.**
22d00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
22d10 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 number of terms
22d20 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
22d30 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
22d40 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
22d50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
22d60 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c E_OP]] ^(<dt>SQL
22d70 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
22d80 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 P</dt>.** <dd>Th
22d90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
22da0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 of instructions
22db0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 in a virtual ma
22dc0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a chine program.**
22dd0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
22de0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d nt an SQL statem
22df0 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 ent. This limit
22e00 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
22e10 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 y.** enforced, t
22e20 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 hough that might
22e30 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d be added in som
22e40 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
22e50 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f of.** SQLite.</
22e60 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
22e70 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
22e80 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e ION_ARG]] ^(<dt>
22e90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
22ea0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a CTION_ARG</dt>.*
22eb0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
22ec0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 m number of argu
22ed0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 ments on a funct
22ee0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ion.</dd>)^.**.*
22ef0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
22f00 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 _ATTACHED]] ^(<d
22f10 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 t>SQLITE_LIMIT_A
22f20 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 TTACHED</dt>.**
22f30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
22f40 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 number of [ATTAC
22f50 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 H | attached dat
22f60 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a abases].)^</dd>.
22f70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
22f80 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
22f90 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 N_LENGTH]].** ^(
22fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
22fb0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
22fc0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
22fd0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
22fe0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 gth of the patte
22ff0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rn argument to t
23000 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 he [LIKE] or.**
23010 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 [GLOB] operators
23020 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
23030 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
23040 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a RIABLE_NUMBER]].
23050 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
23060 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
23070 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 UMBER</dt>.** <d
23080 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e d>The maximum in
23090 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e dex number of an
230a0 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e y [parameter] in
230b0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
230c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c t.)^.**.** [[SQL
230d0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 ITE_LIMIT_TRIGGE
230e0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e R_DEPTH]] ^(<dt>
230f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
23100 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a GGER_DEPTH</dt>.
23110 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
23120 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 um depth of recu
23130 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 rsion for trigge
23140 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f rs.</dd>)^.** </
23150 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
23160 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
23170 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
23180 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
23190 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
231a0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
231b0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
231c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
231d0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 LUMN
231e0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
231f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 e SQLITE_LIMIT_E
23200 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 XPR_DEPTH
23210 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
23220 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
23230 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 COMPOUND_SELECT
23240 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
23250 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
23260 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 _VDBE_OP
23270 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
23280 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
23290 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 T_FUNCTION_ARG
232a0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
232b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
232c0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 IT_ATTACHED
232d0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
232e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
232f0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
23300 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a _LENGTH 8.
23310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
23320 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
23330 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 MBER 9
23340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
23350 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
23360 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 PTH 1
23370 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
23380 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 F: Compiling An
23390 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL Statement.**
233a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
233b0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
233c0 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 er}.**.** To exe
233d0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 cute an SQL quer
233e0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 y, it must first
233f0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 be compiled int
23400 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a o a byte-code.**
23410 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f program using o
23420 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ne of these rout
23430 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
23440 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
23450 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
23460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
23470 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
23480 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 .** prior succes
23490 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
234a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
234b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
234c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
234d0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 3_open16()]. Th
234e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
234f0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 ction must not h
23500 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e ave been closed.
23510 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
23520 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 d argument, "zSq
23530 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 l", is the state
23540 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
23550 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
23560 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
23570 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
23580 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
23590 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
235a0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e epare_v2().** in
235b0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 terfaces use UTF
235c0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f -8, and sqlite3_
235d0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 prepare16() and
235e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
235f0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 6_v2().** use UT
23600 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 F-16..**.** ^If
23610 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 the nByte argume
23620 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 nt is less than
23630 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 zero, then zSql
23640 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
23650 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 e.** first zero
23660 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 terminator. ^If
23670 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
23680 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 ative, then it i
23690 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
236a0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 number of byte
236b0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
236c0 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 . ^When nByte i
236d0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
236e0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 the.** zSql stri
236f0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 ng ends at eithe
23700 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 r the first '\00
23710 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 0' or '\u0000' c
23720 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 haracter or.** t
23730 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 he nByte-th byte
23740 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
23750 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 s first. If the
23760 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 caller knows.**
23770 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
23780 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
23790 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
237a0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c there is a smal
237b0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 l.** performance
237c0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 advantage to be
237d0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 gained by passi
237e0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 ng an nByte para
237f0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 meter that.** is
23800 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 equal to the nu
23810 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
23820 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
23830 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f g <i>including</
23840 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 i>.** the nul-te
23850 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 rminator bytes a
23860 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c s this saves SQL
23870 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 ite from having
23880 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 to.** make a cop
23890 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 y of the input s
238a0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 tring..**.** ^If
238b0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e pzTail is not N
238c0 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c ULL then *pzTail
238d0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e is made to poin
238e0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 t to the first b
238f0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 yte.** past the
23900 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 end of the first
23910 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
23920 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 n zSql. These r
23930 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 outines only.**
23940 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 compile the firs
23950 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a t statement in z
23960 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 Sql, so *pzTail
23970 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
23980 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 to.** what rema
23990 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a ins uncompiled..
239a0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 **.** ^*ppStmt i
239b0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
239c0 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 to a compiled [p
239d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
239e0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a t] that can be.*
239f0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 * executed using
23a00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
23a10 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 ]. ^If there is
23a20 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 an error, *ppSt
23a30 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 mt is set.** to
23a40 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 NULL. ^If the i
23a50 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 nput text contai
23a60 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 ns no SQL (if th
23a70 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d e input is an em
23a80 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 pty.** string or
23a90 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e a comment) then
23aa0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 *ppStmt is set
23ab0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 to NULL..** The
23ac0 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 calling procedur
23ad0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 e is responsible
23ae0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 for deleting th
23af0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 e compiled.** SQ
23b00 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e L statement usin
23b10 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
23b20 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 ize()] after it
23b30 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
23b40 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 h it..** ppStmt
23b50 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e may not be NULL.
23b60 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 .**.** ^On succe
23b70 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ss, the sqlite3_
23b80 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 prepare() family
23b90 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 of routines ret
23ba0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b urn [SQLITE_OK];
23bb0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e .** otherwise an
23bc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
23bd0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
23be0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
23bf0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 pare_v2() and sq
23c00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
23c10 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 v2() interfaces
23c20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 are.** recommend
23c30 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 ed for all new p
23c40 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f rograms. The two
23c50 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 older interface
23c60 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a s are retained.*
23c70 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 * for backwards
23c80 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 compatibility, b
23c90 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 ut their use is
23ca0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 discouraged..**
23cb0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 ^In the "v2" int
23cc0 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 erfaces, the pre
23cd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
23ce0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 ** that is retur
23cf0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ned (the [sqlite
23d00 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 3_stmt] object)
23d10 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 contains a copy
23d20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e of the.** origin
23d30 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 al SQL text. Thi
23d40 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 s causes the [sq
23d50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e lite3_step()] in
23d60 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 terface to.** be
23d70 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 have differently
23d80 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a in three ways:.
23d90 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
23da0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 i>.** ^If the da
23db0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
23dc0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f anges, instead o
23dd0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c f returning [SQL
23de0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 ITE_SCHEMA] as i
23df0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 t.** always used
23e00 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 to do, [sqlite3
23e10 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 _step()] will au
23e20 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
23e30 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a mpile the SQL.**
23e40 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
23e50 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 ry to run it aga
23e60 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a in..** </li>.**.
23e70 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e ** <li>.** ^When
23e80 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
23e90 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
23ea0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f )] will return o
23eb0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c ne of the detail
23ec0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ed.** [error cod
23ed0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 es] or [extended
23ee0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 error codes].
23ef0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 ^The legacy beha
23f00 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a vior was that.**
23f10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
23f20 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 ] would only ret
23f30 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 urn a generic [S
23f40 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 QLITE_ERROR] res
23f50 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 ult code.** and
23f60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
23f70 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 would have to ma
23f80 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c ke a second call
23f90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
23fa0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 et()].** in orde
23fb0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e r to find the un
23fc0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f derlying cause o
23fd0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 f the problem. W
23fe0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 ith the "v2" pre
23ff0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 pare.** interfac
24000 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 es, the underlyi
24010 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 ng reason for th
24020 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 e error is retur
24030 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
24040 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
24050 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
24060 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 specific value b
24070 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 ound to [paramet
24080 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 er | host parame
24090 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 ter] in the .**
240a0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 WHERE clause mig
240b0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
240c0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
240d0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 plan for a stat
240e0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 ement,.** then t
240f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c he statement wil
24100 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c l be automatical
24110 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 ly recompiled, a
24120 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 s if there had b
24130 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 een .** a schema
24140 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 change, on the
24150 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f first [sqlite3_
24160 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c step()] call fol
24170 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 lowing any chang
24180 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c e.** to the [sql
24190 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c ite3_bind_text |
241a0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 bindings] of th
241b0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 at [parameter].
241c0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 .** ^The specifi
241d0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 c value of WHERE
241e0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 -clause [paramet
241f0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 er] might influe
24200 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 nce the .** choi
24210 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e ce of query plan
24220 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
24230 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 r is the left-ha
24240 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 nd side of a [LI
24250 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d KE].** or [GLOB]
24260 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 operator or if
24270 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
24280 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 compared to an
24290 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a indexed column.*
242a0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 * and the [SQLIT
242b0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 E_ENABLE_STAT3]
242c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
242d0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a ion is enabled..
242e0 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e ** the .** </li>
242f0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c .** </ol>.*/.SQL
24300 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
24310 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 te3_prepare(. s
24320 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
24330 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
24340 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
24350 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
24360 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
24370 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
24380 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
24390 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
243a0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
243b0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
243c0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
243d0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
243e0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
243f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
24400 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
24410 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
24420 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
24430 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
24440 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
24450 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
24460 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 3_prepare_v2(.
24470 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
24480 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
24490 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
244a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
244b0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
244c0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 tatement, UTF-8
244d0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
244e0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
244f0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
24500 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
24510 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
24520 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
24530 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
24540 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
24550 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
24560 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
24570 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
24580 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
24590 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 zSql */.);.SQLI
245a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
245b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 e3_prepare16(.
245c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
245d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
245e0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
245f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
24600 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
24610 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
24620 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
24630 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
24640 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
24650 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
24660 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
24670 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
24680 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
24690 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
246a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
246b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
246c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
246d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
246e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c f zSql */.);.SQL
246f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
24700 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
24710 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
24720 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
24730 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
24740 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
24750 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
24760 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
24770 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
24780 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
24790 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
247a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
247b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
247c0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
247d0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
247e0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
247f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
24800 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
24810 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
24820 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
24830 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
24840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
24850 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 : Retrieving Sta
24860 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a tement SQL.**.**
24870 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
24880 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
24890 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 retrieve a saved
248a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 copy of the ori
248b0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 ginal.** SQL tex
248c0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 t used to create
248d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
248e0 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 tement] if that
248f0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a statement was.**
24900 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 compiled using
24910 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f either [sqlite3_
24920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
24930 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
24940 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 e16_v2()]..*/.SQ
24950 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
24960 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c har *sqlite3_sql
24970 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
24980 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
24990 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
249a0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
249b0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 ement Writes The
249c0 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 Database.**.**
249d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
249e0 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e t_readonly(X) in
249f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
24a00 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 true (non-zero)
24a10 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 if.** and only i
24a20 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 f the [prepared
24a30 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b statement] X mak
24a40 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 es no direct cha
24a50 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 nges to.** the c
24a60 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 ontent of the da
24a70 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a tabase file..**.
24a80 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 ** Note that [ap
24a90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
24aa0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
24ab0 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 or.** [virtual
24ac0 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 tables] might ch
24ad0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 ange the databas
24ae0 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 e indirectly as
24af0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 a side effect.
24b00 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c .** ^(For exampl
24b10 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 e, if an applica
24b20 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 tion defines a f
24b30 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 unction "eval()"
24b40 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 that .** calls
24b50 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
24b60 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f , then the follo
24b70 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 wing SQL stateme
24b80 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e nt would.** chan
24b90 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
24ba0 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 file through sid
24bb0 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a e-effects:.**.**
24bc0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
24bd0 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 e>.** SELECT
24be0 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f eval('DELETE FRO
24bf0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a M t1') FROM t2;.
24c00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
24c10 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 quote>.**.** But
24c20 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 because the [SE
24c30 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
24c40 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
24c50 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
24c60 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 e.** directly, s
24c70 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
24c80 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 only() would sti
24c90 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 ll return true.)
24ca0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 ^.**.** ^Transac
24cb0 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 tion control sta
24cc0 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 tements such as
24cd0 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 [BEGIN], [COMMIT
24ce0 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a ], [ROLLBACK],.*
24cf0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 * [SAVEPOINT], a
24d00 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 nd [RELEASE] cau
24d10 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f se sqlite3_stmt_
24d20 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 readonly() to re
24d30 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 turn true,.** si
24d40 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e nce the statemen
24d50 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f ts themselves do
24d60 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f not actually mo
24d70 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 dify the databas
24d80 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 e but.** rather
24d90 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 they control the
24da0 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 timing of when
24db0 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 other statements
24dc0 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 modify the .**
24dd0 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 database. ^The
24de0 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 [ATTACH] and [DE
24df0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 TACH] statements
24e00 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 also cause.** s
24e10 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
24e20 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
24e30 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 true since, whi
24e40 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 le those stateme
24e50 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 nts.** change th
24e60 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
24e70 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f of a database co
24e80 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 nnection, they d
24e90 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 o not make .** c
24ea0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f hanges to the co
24eb0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 ntent of the dat
24ec0 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 abase files on d
24ed0 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 isk..*/.SQLITE_A
24ee0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 PI int sqlite3_s
24ef0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c tmt_readonly(sql
24f00 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
24f10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
24f20 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
24f30 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
24f40 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 ement Has Been R
24f50 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eset.**.** ^The
24f60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
24f70 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 y(S) interface r
24f80 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e eturns true (non
24f90 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a -zero) if the.**
24fa0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
24fb0 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e ment] S has been
24fc0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 stepped at leas
24fd0 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a t once using .**
24fe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
24ff0 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 )] but has not r
25000 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e un to completion
25010 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 and/or has not
25020 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 .** been reset u
25030 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
25040 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 set(S)]. ^The s
25050 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
25060 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 (S).** interface
25070 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 returns false i
25080 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f S is a NULL po
25090 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 inter. If S is
250a0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 not a .** NULL p
250b0 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f ointer and is no
250c0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 t a pointer to a
250d0 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 valid [prepared
250e0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
250f0 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 bject, then the
25100 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
25110 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
25120 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a ly undesirable..
25130 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
25140 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
25150 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 in combination
25160 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
25170 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 mt()].** to loca
25180 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 te all prepared
25190 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 statements assoc
251a0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 iated with a dat
251b0 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 abase .** connec
251c0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e tion that are in
251d0 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 need of being r
251e0 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 eset. This can
251f0 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 be used,.** for
25200 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 example, in diag
25210 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 nostic routines
25220 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 to search for pr
25230 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 epared .** state
25240 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 ments that are h
25250 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 olding a transac
25260 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 tion open..*/.SQ
25270 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
25280 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 ite3_stmt_busy(s
25290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
252a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
252b0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
252c0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a d Value Object.*
252d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
252e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
252f0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
25300 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
25310 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
25320 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
25330 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
25340 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
25350 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
25360 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
25370 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
25380 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
25390 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
253a0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
253b0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 stores. ^Values
253c0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
253d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
253e0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
253f0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
25400 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
25410 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
25420 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
25430 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
25440 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
25450 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
25460 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
25470 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
25480 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
25490 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
254a0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
254b0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
254c0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
254d0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
254e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
254f0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
25500 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
25510 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
25520 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
25530 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
25540 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
25550 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
25560 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
25570 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
25580 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
25590 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
255a0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
255b0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
255c0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
255d0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 An internal mute
255e0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 x is held for a
255f0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
25600 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
25610 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 t but no mutex i
25620 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e s held for an un
25630 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
25640 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
25650 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 t. If SQLite is
25660 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 compiled to be
25670 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a single-threaded.
25680 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 ** (with [SQLITE
25690 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 _THREADSAFE=0] a
256a0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 nd with [sqlite3
256b0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 _threadsafe()] r
256c0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f eturning 0).** o
256d0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 r if SQLite is r
256e0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 un in one of red
256f0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 uced mutex modes
25700 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [SQLITE_CON
25710 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
25720 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
25730 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
25740 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 .** then there i
25750 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e s no distinction
25760 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
25770 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
25780 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
25790 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 lue objects and
257a0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 they can be used
257b0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 interchangeably
257c0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
257d0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 or maximum code
257e0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 portability it i
257f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
25800 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a at applications.
25810 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 ** still make th
25820 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 e distinction be
25830 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
25840 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
25850 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
25860 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 objects even wh
25870 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 en not strictly
25880 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
25890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
258a0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 ue objects that
258b0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 are passed as pa
258c0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 rameters into th
258d0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
258e0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 ion of [applicat
258f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
25900 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 functions] are p
25910 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 rotected..** ^Th
25920 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
25930 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
25940 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
25950 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
25960 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a s unprotected..*
25970 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 * Unprotected sq
25980 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
25990 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 cts may only be
259a0 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 used with.** [sq
259b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
259c0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
259d0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
259e0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
259f0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 3_value_blob | s
25a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
25a10 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a e()] family of.*
25a20 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 * interfaces req
25a30 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 uire protected s
25a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
25a50 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ects..*/.typedef
25a60 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 struct Mem sqli
25a70 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a te3_value;../*.*
25a80 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
25a90 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
25aa0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
25ab0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 e context in whi
25ac0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 ch an SQL functi
25ad0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 on executes is s
25ae0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 tored in an.** s
25af0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
25b00 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 bject. ^A point
25b10 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 er to an sqlite3
25b20 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a _context object.
25b30 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 ** is always fir
25b40 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
25b50 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
25b60 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
25b70 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c ns]..** The appl
25b80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
25b90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
25ba0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c lementation will
25bb0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f pass this.** po
25bc0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e inter through in
25bd0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c to calls to [sql
25be0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 ite3_result_int
25bf0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 | sqlite3_result
25c00 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
25c10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
25c20 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f xt()], [sqlite3_
25c30 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a user_data()],.**
25c40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
25c50 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 t_db_handle()],
25c60 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 [sqlite3_get_aux
25c70 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f data()],.** and/
25c80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f or [sqlite3_set_
25c90 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 auxdata()]..*/.t
25ca0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
25cb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 lite3_context sq
25cc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a lite3_context;..
25cd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
25ce0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 Binding Values T
25cf0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 o Prepared State
25d00 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ments.** KEYWORD
25d10 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 S: {host paramet
25d20 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 er} {host parame
25d30 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 ters} {host para
25d40 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b meter name}.** K
25d50 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 EYWORDS: {SQL pa
25d60 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 rameter} {SQL pa
25d70 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d rameters} {param
25d80 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a eter binding}.**
25d90 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c .** ^(In the SQL
25da0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
25db0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
25dc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
25dd0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
25de0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 ,.** literals ma
25df0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 y be replaced by
25e00 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 a [parameter] t
25e10 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 hat matches one
25e20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 of following.**
25e30 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a templates:.**.**
25e40 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
25e50 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
25e60 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
25e70 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
25e80 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
25e90 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 >.**.** In the t
25ea0 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 emplates above,
25eb0 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 NNN represents a
25ec0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 n integer litera
25ed0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 l,.** and VVV re
25ee0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 presents an alph
25ef0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 anumeric identif
25f00 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c ier.)^ ^The val
25f10 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ues of these.**
25f20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f parameters (also
25f30 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 called "host pa
25f40 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f rameter names" o
25f50 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 r "SQL parameter
25f60 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 s").** can be se
25f70 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 t using the sqli
25f80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
25f90 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 tines defined he
25fa0 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 re..**.** ^The f
25fb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
25fc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
25fd0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 d_*() routines i
25fe0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f s always.** a po
25ff0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
26000 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
26010 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ct returned from
26020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
26030 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
26040 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a s variants..**.*
26050 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 * ^The second ar
26060 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
26070 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 dex of the SQL p
26080 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 arameter to be s
26090 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 et..** ^The left
260a0 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 most SQL paramet
260b0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
260c0 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 of 1. ^When the
260d0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 same named.** S
260e0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
260f0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f used more than o
26100 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 nce, second and
26110 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 subsequent.** oc
26120 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 currences have t
26130 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 he same index as
26140 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 the first occur
26150 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 rence..** ^The i
26160 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 ndex for named p
26170 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 arameters can be
26180 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 looked up using
26190 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
261a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
261b0 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 index()] API if
261c0 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 desired. ^The i
261d0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
261e0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
261f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
26200 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 N..** ^The NNN v
26210 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
26220 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
26230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
26240 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
26250 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
26260 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
26270 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
26280 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 )..**.** ^The th
26290 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
262a0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e the value to bin
262b0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 d to the paramet
262c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 er..**.** ^(In t
262d0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 hose routines th
262e0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 at have a fourth
262f0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 argument, its v
26300 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
26310 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
26320 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e n the parameter.
26330 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 To be clear: t
26340 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a he value is the.
26350 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e ** number of <u>
26360 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 bytes</u> in the
26370 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 value, not the
26380 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
26390 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 ters.)^.** ^If t
263a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
263b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
263c0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
263d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
263e0 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 6().** is negati
263f0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e ve, then the len
26400 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
26410 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 g is.** the numb
26420 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 er of bytes up t
26430 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
26440 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 terminator..**
26450 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
26460 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
26470 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
26480 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
26490 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 .** the behavior
264a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
264b0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 * If a non-negat
264c0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d ive fourth param
264d0 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 eter is provided
264e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
264f0 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _text().** or sq
26500 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
26510 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 6() then that pa
26520 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
26530 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a the byte offset.
26540 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c ** where the NUL
26550 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c terminator woul
26560 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 d occur assuming
26570 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 the string were
26580 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 NUL.** terminat
26590 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 ed. If any NUL
265a0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 characters occur
265b0 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 at byte offsets
265c0 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 less than .** t
265d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
265e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
265f0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
26600 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 ing string value
26610 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e will.** contain
26620 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 embedded NULs.
26630 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 The result of e
26640 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c xpressions invol
26650 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 ving strings.**
26660 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 with embedded NU
26670 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e Ls is undefined.
26680 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 .**.** ^The fift
26690 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
266a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
266b0 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ), sqlite3_bind_
266c0 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 text(), and.** s
266d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
266e0 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 16() is a destru
266f0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 ctor used to dis
26700 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
26710 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 or.** string af
26720 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 ter SQLite has f
26730 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
26740 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f ^The destructo
26750 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 r is called.** t
26760 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
26770 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 BLOB or string
26780 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c even if the call
26790 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
267a0 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 _blob(),.** sqli
267b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c te3_bind_text(),
267c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
267d0 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e _text16() fails.
267e0 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 .** ^If the fi
267f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
26800 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
26810 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
26820 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
26830 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
26840 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
26850 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
26860 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
26870 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
26880 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
26890 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
268a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
268b0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
268c0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
268d0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
268e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
268f0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
26900 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
26910 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
26920 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
26930 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
26940 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
26950 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
26960 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 routine binds a
26970 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 BLOB of length
26980 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c N that.** is fil
26990 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e led with zeroes.
269a0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 ^A zeroblob us
269b0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e es a fixed amoun
269c0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 t of memory.** (
269d0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 just an integer
269e0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 to hold its size
269f0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 ) while it is be
26a00 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a ing processed..*
26a10 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 * Zeroblobs are
26a20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 intended to serv
26a30 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 e as placeholder
26a40 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 s for BLOBs whos
26a50 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 e.** content is
26a60 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 later written us
26a70 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
26a80 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
26a90 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
26aa0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e ] routines..** ^
26ab0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
26ac0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
26ad0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
26ae0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
26af0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
26b00 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
26b10 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
26b20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
26b30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
26b40 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
26b50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
26b60 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
26b70 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
26b80 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
26b90 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
26ba0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
26bb0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
26bc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
26bd0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
26be0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
26bf0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
26c00 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
26c10 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
26c20 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
26c30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26c40 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
26c50 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
26c60 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
26c70 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
26c80 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
26c90 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
26ca0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
26cb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
26cc0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
26cd0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
26ce0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
26cf0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
26d00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
26d10 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
26d20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
26d30 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
26d40 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
26d50 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
26d60 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
26d70 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 ^[SQLITE_RANGE]
26d80 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
26d90 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
26da0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
26db0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 range. ^[SQLITE
26dc0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 _NOMEM] is retur
26dd0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 ned if malloc()
26de0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fails..**.** See
26df0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
26e00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
26e10 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ount()],.** [sql
26e20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
26e30 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
26e40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
26e50 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
26e60 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
26e70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
26e80 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
26e90 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
26ea0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
26eb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
26ec0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
26ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
26ee0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
26ef0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
26f00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
26f10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 qlite3_bind_int(
26f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
26f30 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 nt, int);.SQLITE
26f40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
26f50 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
26f60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
26f70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
26f80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
26f90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
26fa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
26fb0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
26fc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
26fd0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
26fe0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
26ff0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 char*, int n, v
27000 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
27010 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
27020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
27030 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
27040 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
27050 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
27060 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
27070 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
27080 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 _bind_value(sqli
27090 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
270a0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
270b0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
270c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
270d0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
270e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
270f0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
27100 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
27110 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
27120 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f s.**.** ^This ro
27130 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 utine can be use
27140 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
27150 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 mber of [SQL par
27160 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 ameters].** in a
27170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
27180 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 ment]. SQL para
27190 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e meters are token
271a0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d s of the.** form
271b0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a "?", "?NNN", ":
271c0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 AAA", "$AAA", or
271d0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 "@AAA" that ser
271e0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f ve as.** placeho
271f0 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 lders for values
27200 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 that are [sqlit
27210 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
27220 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 ound].** to the
27230 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 parameters at a
27240 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a later time..**.*
27250 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
27260 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e actually return
27270 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
27280 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 he largest (righ
27290 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 tmost).** parame
272a0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 ter. For all for
272b0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 ms except ?NNN,
272c0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 this will corres
272d0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e pond to the.** n
272e0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 umber of unique
272f0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 parameters. If
27300 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
27310 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 e ?NNN form are
27320 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d used,.** there m
27330 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 ay be gaps in th
27340 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 e list.)^.**.**
27350 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
27360 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
27370 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
27380 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
27390 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
273a0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
273b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
273c0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
273d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
273e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
273f0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ter_count(sqlite
27400 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
27410 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
27420 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 Of A Host Parame
27430 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ter.**.** ^The s
27440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
27450 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 meter_name(P,N)
27460 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27470 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 s.** the name of
27480 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 the N-th [SQL p
27490 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
274a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
274b0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 ment] P..** ^(SQ
274c0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
274d0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
274e0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
274f0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
27500 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
27510 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
27520 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
27530 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
27540 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
27550 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
27560 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
27570 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
27580 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
27590 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
275a0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
275b0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 e.)^.** ^Paramet
275c0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
275d0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f "?" without a fo
275e0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 llowing integer
275f0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 have no name.**
27600 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 and are referred
27610 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 to as "nameless
27620 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 " or "anonymous
27630 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a parameters"..**.
27640 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f ** ^The first ho
27650 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 st parameter has
27660 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 an index of 1,
27670 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 not 0..**.** ^If
27680 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 the value N is
27690 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
276a0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 if the N-th para
276b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 meter is.** name
276c0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 less, then NULL
276d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 is returned. ^T
276e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
276f0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 ng is.** always
27700 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e in UTF-8 encodin
27710 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 g even if the na
27720 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 med parameter wa
27730 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 s.** originally
27740 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 specified as UTF
27750 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f -16 in [sqlite3_
27760 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a prepare16()] or.
27770 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
27780 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
27790 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
277a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
277b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
277c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
277d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
277e0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
277f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
27800 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
27810 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
27820 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
27830 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
27840 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
27850 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
27860 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
27870 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
27880 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
27890 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 e.**.** ^Return
278a0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 the index of an
278b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 SQL parameter gi
278c0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e ven its name. ^
278d0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c The.** index val
278e0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 ue returned is s
278f0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 uitable for use
27900 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
27910 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
27920 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
27930 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
27940 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 . ^A zero.** is
27950 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 returned if no
27960 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 matching paramet
27970 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 er is found. ^T
27980 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
27990 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
279a0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
279b0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
279c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
279d0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
279e0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
279f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
27a00 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
27a10 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
27a20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
27a30 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
27a40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
27a50 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
27a60 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
27a70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
27a80 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
27a90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
27aa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
27ab0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
27ac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
27ad0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
27ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27af0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
27b00 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
27b10 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d Statement.**.*
27b20 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 * ^Contrary to t
27b30 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
27b40 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
27b50 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
27b60 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
27b70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
27b80 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
27b90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
27ba0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 ement]..** ^Use
27bb0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 this routine to
27bc0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 reset all host p
27bd0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c arameters to NUL
27be0 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 L..*/.SQLITE_API
27bf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 int sqlite3_cle
27c00 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 ar_bindings(sqli
27c10 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
27c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
27c30 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 ber Of Columns I
27c40 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a n A Result Set.*
27c50 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
27c60 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
27c70 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
27c80 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
27c90 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
27ca0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 d statement]. ^T
27cb0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
27cc0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 rns 0 if pStmt i
27cd0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 s an SQL.** stat
27ce0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 ement that does
27cf0 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 not return data
27d00 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 (for example an
27d10 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a [UPDATE])..**.**
27d20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
27d30 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
27d40 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
27d50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
27d60 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 mn_count(sqlite3
27d70 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
27d80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27d90 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 Column Names In
27da0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a A Result Set.**.
27db0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
27dc0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 es return the na
27dd0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 me assigned to a
27de0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 particular colu
27df0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 mn.** in the res
27e00 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
27e10 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
27e20 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ^The sqlite3_c
27e30 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 olumn_name().**
27e40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27e50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
27e60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
27e70 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
27e80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
27e90 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 umn_name16() ret
27ea0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
27eb0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
27ec0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
27ed0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 ring. ^The firs
27ee0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
27ef0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
27f00 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
27f10 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
27f20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
27f30 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 t. ^The second p
27f40 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
27f50 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 ** column number
27f60 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 . ^The leftmost
27f70 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 column is numbe
27f80 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 r 0..**.** ^The
27f90 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
27fa0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
27fb0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
27fc0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
27fd0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 ement].** is des
27fe0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
27ff0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
28000 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
28010 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
28020 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
28030 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
28040 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
28050 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
28060 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
28070 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
28080 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 next call to.**
28090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
280a0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ame() or sqlite3
280b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
280c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c on the same col
280d0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 umn..**.** ^If s
280e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
280f0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 fails during the
28100 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 processing of e
28110 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a ither routine.**
28120 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 (for example du
28130 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f ring a conversio
28140 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 n from UTF-8 to
28150 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a UTF-16) then a.*
28160 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
28170 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
28180 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 * ^The name of a
28190 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
281a0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
281b0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 he "AS" clause f
281c0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d or.** that colum
281d0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 n, if there is a
281e0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 n AS clause. If
281f0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 there is no AS
28200 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 clause.** then t
28210 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
28220 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 olumn is unspeci
28230 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 fied and may cha
28240 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 nge from.** one
28250 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
28260 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
28270 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
28280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
28290 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c _column_name(sql
282a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
282b0 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 N);.SQLITE_API c
282c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
282d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
282e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
282f0 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int N);../*.** C
28300 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 API3REF: Source
28310 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 Of Data In A Que
28320 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 ry Result.**.**
28330 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
28340 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 provide a means
28350 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 to determine the
28360 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
28370 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 , and.** table c
28380 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 olumn that is th
28390 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 e origin of a pa
283a0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 rticular result
283b0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 column in.** [SE
283c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
283d0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
283e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 the database or
283f0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
28400 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
28410 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 as.** either a
28420 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
28430 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 string. ^The _d
28440 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
28450 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
28460 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
28470 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
28480 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
28490 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
284a0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
284b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
284c0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
284d0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
284e0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 string is valid
284f0 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 until the [prepa
28500 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
28510 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 s destroyed.** u
28520 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
28530 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
28540 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 il the statement
28550 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
28560 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 y.** reprepared
28570 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c by the first cal
28580 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
28590 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 ep()] for a part
285a0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 icular run.** or
285b0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 until the same
285c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 information is r
285d0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 equested.** agai
285e0 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 n in a different
285f0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
28600 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 ^The names retu
28610 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 rned are the ori
28620 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 ginal un-aliased
28630 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
28640 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
28650 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a , and column..**
28660 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
28670 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 rgument to these
28680 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 interfaces is a
28690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
286a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 ment]..** ^These
286b0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
286c0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
286d0 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 out the Nth resu
286e0 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e lt column return
286f0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 ed by.** the sta
28700 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 tement, where N
28710 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 is the second fu
28720 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
28730 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f .** ^The left-mo
28740 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c st column is col
28750 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 umn 0 for these
28760 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
28770 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
28780 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 mn returned by t
28790 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
287a0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 an expression or
287b0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 .** subquery and
287c0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e is not a column
287d0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c value, then all
287e0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
287f0 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 ons return.** NU
28800 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 LL. ^These rout
28810 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 ine might also r
28820 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 eturn NULL if a
28830 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
28840 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 n error.** occur
28850 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 s. ^Otherwise,
28860 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
28870 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 name of the atta
28880 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 ched database, t
28890 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 able,.** or colu
288a0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
288b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
288c0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
288d0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 **.** ^As with a
288e0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ll other SQLite
288f0 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 APIs, those whos
28900 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 e names end with
28910 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
28920 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
28930 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f trings and the o
28940 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
28950 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a eturn UTF-8..**.
28960 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 ** ^These APIs a
28970 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
28980 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
28990 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
289a0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
289b0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
289c0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
289d0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e rocessor symbol.
289e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
289f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
28a00 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f ll one or more o
28a10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
28a20 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d against the sam
28a30 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 e.** prepared st
28a40 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 atement and colu
28a50 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 mn at the same t
28a60 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
28a70 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 ults are.** unde
28a80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
28a90 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
28aa0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
28ab0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 more.** [sqlite3
28ac0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
28ad0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
28ae0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
28af0 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 es].** for the s
28b00 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ame [prepared st
28b10 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 atement] and res
28b20 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 ult column.** at
28b30 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
28b40 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
28b50 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
28b60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
28b70 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
28b80 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
28b90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
28ba0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
28bb0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
28bc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
28bd0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
28be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
28bf0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
28c00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
28c10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
28c20 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
28c30 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
28c40 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
28c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
28c60 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 able_name16(sqli
28c70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
28c80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
28c90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
28ca0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d olumn_origin_nam
28cb0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
28cc0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
28cd0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
28ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
28cf0 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 in_name16(sqlite
28d00 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
28d10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
28d20 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 eclared Datatype
28d30 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 Of A Query Resu
28d40 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 lt.**.** ^(The f
28d50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
28d60 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
28d70 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 atement]..** If
28d80 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 this statement i
28d90 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 s a [SELECT] sta
28da0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e tement and the N
28db0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
28dc0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 .** returned res
28dd0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 ult set of that
28de0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 [SELECT] is a ta
28df0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 ble column (not
28e00 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
28e10 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 or subquery) th
28e20 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 en the declared
28e30 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
28e40 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 e.** column is r
28e50 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 eturned.)^ ^If
28e60 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
28e70 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
28e80 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 is an.** expres
28e90 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
28ea0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f , then a NULL po
28eb0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
28ec0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 d..** ^The retur
28ed0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c ned string is al
28ee0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 ways UTF-8 encod
28ef0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 ed..**.** ^(For
28f00 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 example, given t
28f10 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
28f20 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 ma:.**.** CREATE
28f30 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 TABLE t1(c1 VAR
28f40 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 IANT);.**.** and
28f50 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
28f60 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
28f70 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 ompiled:.**.** S
28f80 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 ELECT c1 + 1, c1
28f90 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 FROM t1;.**.**
28fa0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 this routine wou
28fb0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 ld return the st
28fc0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 ring "VARIANT" f
28fd0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 or the second re
28fe0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 sult.** column (
28ff0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c i==1), and a NUL
29000 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 L pointer for th
29010 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 e first result c
29020 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a olumn (i==0).)^.
29030 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
29040 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 es dynamic run-t
29050 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f ime typing. ^So
29060 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 just because a
29070 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 column.** is dec
29080 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e lared to contain
29090 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 a particular ty
290a0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e pe does not mean
290b0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 that the.** dat
290c0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 a stored in that
290d0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 column is of th
290e0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e e declared type.
290f0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 SQLite is.** s
29100 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 trongly typed, b
29110 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 ut the typing is
29120 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 dynamic not sta
29130 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 tic. ^Type.** i
29140 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
29150 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c h individual val
29160 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 ues, not with th
29170 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 e containers.**
29180 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f used to hold tho
29190 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 se values..*/.SQ
291a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
291b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
291c0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c umn_decltype(sql
291d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
291e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
291f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
29200 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
29210 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
29220 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
29230 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
29240 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
29250 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
29260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29270 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
29280 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
29290 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
292a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
292b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
292c0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
292d0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
292e0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
292f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
29300 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
29310 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
29320 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
29330 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
29340 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
29350 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
29360 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
29370 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
29380 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
29390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
293a0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
293b0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
293c0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
293d0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
293e0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
293f0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
29400 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
29410 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
29420 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
29430 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
29440 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
29450 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
29460 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
29470 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
29480 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
29490 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
294a0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
294b0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
294c0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
294d0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
294e0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
294f0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
29500 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 ed..**.** ^In th
29510 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
29520 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ce, the return v
29530 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 alue will be eit
29540 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 her [SQLITE_BUSY
29550 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ],.** [SQLITE_DO
29560 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 NE], [SQLITE_ROW
29570 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ], [SQLITE_ERROR
29580 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
29590 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 SUSE]..** ^With
295a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
295b0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
295c0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
295d0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
295e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
295f0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
29600 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
29610 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 ** ^[SQLITE_BUSY
29620 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
29630 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
29640 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 was unable to a
29650 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 cquire the.** da
29660 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 tabase locks it
29670 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 needs to do its
29680 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 job. ^If the st
29690 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
296a0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
296b0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
296c0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
296d0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
296e0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
296f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
29700 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
29710 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
29720 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
29730 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 n an.** explicit
29740 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
29750 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
29760 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
29770 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
29780 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
29790 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d * ^[SQLITE_DONE]
297a0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
297b0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 statement has fi
297c0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
297d0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
297e0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
297f0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
29800 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 called again on
29810 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 this virtual.**
29820 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 machine without
29830 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 first calling [s
29840 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
29850 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 to reset the vir
29860 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
29870 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
29880 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a ial state..**.**
29890 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 ^If the SQL sta
298a0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
298b0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
298c0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
298d0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
298e0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
298f0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
29900 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
29910 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
29920 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
29930 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
29940 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
29950 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
29960 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
29970 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
29980 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
29990 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
299a0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
299b0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 a..**.** ^[SQLIT
299c0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
299d0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
299e0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
299f0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
29a00 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
29a10 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
29a20 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
29a30 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
29a40 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
29a50 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
29a60 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
29a70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
29a80 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
29a90 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 ^With the legacy
29aa0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f interface, a mo
29ab0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
29ac0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d r code (for exam
29ad0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ple,.** [SQLITE_
29ae0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c INTERRUPT], [SQL
29af0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 ITE_SCHEMA], [SQ
29b00 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 LITE_CORRUPT], a
29b10 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 nd so forth).**
29b20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
29b30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
29b40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 te3_reset()] on
29b50 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
29b60 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 statement]. ^I
29b70 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
29b80 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 face,.** the mor
29b90 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
29ba0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 code is returne
29bb0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 d directly by sq
29bc0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a lite3_step()..**
29bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
29be0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SE] means that t
29bf0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 he this routine
29c00 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 was called inapp
29c10 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 ropriately..** P
29c20 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 erhaps it was ca
29c30 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 lled on a [prepa
29c40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
29c50 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 hat has.** alrea
29c60 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 dy been [sqlite3
29c70 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
29c80 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 lized] or on one
29c90 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 that had.** pre
29ca0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
29cb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
29cc0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
29cd0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a . Or it could.*
29ce0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 * be the case th
29cf0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 at the same data
29d00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
29d10 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 is being used by
29d20 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 two or.** more
29d30 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
29d40 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 ame moment in ti
29d50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c me..**.** For al
29d60 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 l versions of SQ
29d70 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 Lite up to and i
29d80 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e ncluding 3.6.23.
29d90 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 1, a call to.**
29da0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
29db0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 ] was required a
29dc0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 fter sqlite3_ste
29dd0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 p() returned any
29de0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 thing.** other t
29df0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
29e00 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 before any subs
29e10 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
29e20 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n of.** sqlite3_
29e30 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 step(). Failure
29e40 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 to reset the pr
29e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29e60 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
29e70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 te3_reset()] wou
29e80 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 ld result in an
29e90 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
29ea0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 return from.** s
29eb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
29ec0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f But after versio
29ed0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 n 3.6.23.1, sqli
29ee0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e te3_step() began
29ef0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c .** calling [sql
29f00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 ite3_reset()] au
29f10 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 tomatically in t
29f20 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 his circumstance
29f30 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 rather.** than
29f40 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
29f50 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 E_MISUSE]. This
29f60 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 is not consider
29f70 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 ed a compatibili
29f80 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 ty.** break beca
29f90 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 use any applicat
29fa0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 ion that ever re
29fb0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 ceives an SQLITE
29fc0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a _MISUSE error.**
29fd0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 is broken by de
29fe0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b finition. The [
29ff0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
2a000 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 RESET] compile-t
2a010 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 ime option.** ca
2a020 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 n be used to res
2a030 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 tore the legacy
2a040 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
2a050 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
2a060 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
2a070 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
2a080 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
2a090 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
2a0a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
2a0b0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
2a0c0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
2a0d0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
2a0e0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
2a0f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2a100 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
2a110 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
2a120 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
2a130 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2a140 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2a150 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
2a160 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
2a170 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
2a180 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
2a190 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
2a1a0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
2a1b0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
2a1c0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
2a1d0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
2a1e0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
2a1f0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
2a200 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
2a210 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
2a220 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
2a230 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
2a240 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
2a250 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2a260 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2a270 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
2a280 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
2a290 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
2a2a0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
2a2b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2a2c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
2a2d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
2a2e0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
2a2f0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
2a300 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
2a310 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
2a320 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
2a330 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2a340 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2a350 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 d..*/.SQLITE_API
2a360 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 int sqlite3_ste
2a370 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 p(sqlite3_stmt*)
2a380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a390 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c F: Number of col
2a3a0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 umns in a result
2a3b0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 set.**.** ^The
2a3c0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2a3d0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 nt(P) interface
2a3e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2a3f0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2a400 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 the.** current
2a410 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2a420 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 t set of [prepar
2a430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
2a440 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 .** ^If prepared
2a450 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 statement P doe
2a460 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c s not have resul
2a470 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 ts ready to retu
2a480 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 rn.** (via calls
2a490 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
2a4a0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 _column_int | sq
2a4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 lite3_column_*()
2a4c0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 ] of.** interfac
2a4d0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 es) then sqlite3
2a4e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 _data_count(P) r
2a4f0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 eturns 0..** ^Th
2a500 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2a510 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2a520 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 also returns 0 i
2a530 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f P is a NULL po
2a540 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 inter..** ^The s
2a550 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2a560 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 t(P) routine ret
2a570 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 urns 0 if the pr
2a580 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a evious call to.*
2a590 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d * [sqlite3_step]
2a5a0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 (P) returned [SQ
2a5b0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 LITE_DONE]. ^Th
2a5c0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2a5d0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 ount(P).** will
2a5e0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 return non-zero
2a5f0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c if previous call
2a600 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2a610 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a p](P) returned.*
2a620 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 * [SQLITE_ROW],
2a630 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 except in the ca
2a640 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d se of the [PRAGM
2a650 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 A incremental_va
2a660 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 cuum].** where i
2a670 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 t always returns
2a680 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 zero since each
2a690 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 step of that mu
2a6a0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 lti-step.** prag
2a6b0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c ma returns 0 col
2a6c0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a umns of data..**
2a6d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2a6e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
2a6f0 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 unt()].*/.SQLITE
2a700 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2a710 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 _data_count(sqli
2a720 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2a730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a740 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 F: Fundamental D
2a750 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 atatypes.** KEYW
2a760 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
2a770 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 T.**.** ^(Every
2a780 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 value in SQLite
2a790 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 has one of five
2a7a0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 fundamental data
2a7b0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c types:.**.** <ul
2a7c0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 >.** <li> 64-bit
2a7d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
2a7e0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 ** <li> 64-bit I
2a7f0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 EEE floating poi
2a800 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 nt number.** <li
2a810 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e > string.** <li>
2a820 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 BLOB.** <li> NU
2a830 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a LL.** </ul>)^.**
2a840 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
2a850 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f nts are codes fo
2a860 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 r each of those
2a870 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 types..**.** Not
2a880 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 e that the SQLIT
2a890 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 E_TEXT constant
2a8a0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e was also used in
2a8b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2a8c0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 2.** for a compl
2a8d0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 etely different
2a8e0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 meaning. Softwa
2a8f0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 re that links ag
2a900 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 ainst both.** SQ
2a910 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 Lite version 2 a
2a920 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f nd SQLite versio
2a930 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 n 3 should use S
2a940 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 QLITE3_TEXT, not
2a950 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e .** SQLITE_TEXT.
2a960 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2a970 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 TE_INTEGER 1.#d
2a980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f efine SQLITE_FLO
2a990 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 AT 2.#define
2a9a0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 SQLITE_BLOB
2a9b0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
2a9c0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 _NULL 5.#ifd
2a9d0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 ef SQLITE_TEXT.#
2a9e0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 undef SQLITE_TE
2a9f0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e XT.#else.# defin
2aa00 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 e SQLITE_TEXT
2aa10 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 3.#endif.#defi
2aa20 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 ne SQLITE3_TEXT
2aa30 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 3../*.** CAP
2aa40 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 I3REF: Result Va
2aa50 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 lues From A Quer
2aa60 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b y.** KEYWORDS: {
2aa70 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
2aa80 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 nctions}.**.** T
2aa90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hese routines fo
2aaa0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 rm the "result s
2aab0 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a et" interface..*
2aac0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
2aad0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
2aae0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 rmation about a
2aaf0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
2ab00 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
2ab10 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
2ab20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 query. ^In ever
2ab30 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 y case the first
2ab40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
2ab50 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
2ab60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2ab70 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 ment] that is be
2ab80 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 ing evaluated (t
2ab90 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
2aba0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 *].** that was r
2abb0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 eturned from [sq
2abc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2abd0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 ()] or one of it
2abe0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 s variants).** a
2abf0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 nd the second ar
2ac00 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
2ac10 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d dex of the colum
2ac20 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f n for which info
2ac30 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c rmation.** shoul
2ac40 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e d be returned. ^
2ac50 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
2ac60 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
2ac70 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e t set has the in
2ac80 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e dex 0..** ^The n
2ac90 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2aca0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 in the result c
2acb0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 an be determined
2acc0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
2acd0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
2ace0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 )]..**.** If the
2acf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 SQL statement d
2ad00 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c oes not currentl
2ad10 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c y point to a val
2ad20 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 id row, or if th
2ad30 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 e.** column inde
2ad40 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
2ad50 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 e, the result is
2ad60 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
2ad70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 hese routines ma
2ad80 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 y only be called
2ad90 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 when the most r
2ada0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a ecent call to.**
2adb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2adc0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b ] has returned [
2add0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 SQLITE_ROW] and
2ade0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 neither.** [sqli
2adf0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 te3_reset()] nor
2ae00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2ae10 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 ze()] have been
2ae20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e called subsequen
2ae30 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f tly..** If any o
2ae40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2ae50 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 are called afte
2ae60 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
2ae70 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
2ae80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
2ae90 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 r after [sqlite3
2aea0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
2aeb0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 urned.** somethi
2aec0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ng other than [S
2aed0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 QLITE_ROW], the
2aee0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2aef0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 fined..** If [sq
2af00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
2af10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2af20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
2af30 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 inalize()].** ar
2af40 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 e called from a
2af50 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
2af60 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 while any of th
2af70 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
2af80 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 are pending, the
2af90 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
2afa0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
2afb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2afc0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f column_type() ro
2afd0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
2afe0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 e.** [SQLITE_INT
2aff0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 EGER | datatype
2b000 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e code] for the in
2b010 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a itial data type.
2b020 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ** of the result
2b030 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 column. ^The r
2b040 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 eturned value is
2b050 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
2b060 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 INTEGER],.** [SQ
2b070 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 LITE_FLOAT], [SQ
2b080 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c LITE_TEXT], [SQL
2b090 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 ITE_BLOB], or [S
2b0a0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 QLITE_NULL]. Th
2b0b0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
2b0c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2b0d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2b0e0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 only meaningful
2b0f0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f if no type.** co
2b100 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f nversions have o
2b110 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 ccurred as descr
2b120 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 ibed below. Aft
2b130 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
2b140 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c sion,.** the val
2b150 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
2b160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2b170 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 pe() is undefine
2b180 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 d. Future.** ve
2b190 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
2b1a0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 may change the
2b1b0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
2b1c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2b1d0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 ).** following a
2b1e0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2b1f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2b200 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
2b210 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 or UTF-8 string
2b220 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
2b230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2b240 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
2b250 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2b260 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
2b270 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
2b280 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2b290 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 t is a UTF-16 st
2b2a0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
2b2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2b2c0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2b2d0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2b2e0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 8 and then retur
2b2f0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2b300 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 bytes..** ^If t
2b310 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e he result is a n
2b320 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 umeric value the
2b330 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2b340 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a _bytes() uses.**
2b350 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
2b360 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 tf()] to convert
2b370 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 that value to a
2b380 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e UTF-8 string an
2b390 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 d returns.** the
2b3a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2b3b0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e in that string.
2b3c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2b3d0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e lt is NULL, then
2b3e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2b3f0 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 bytes() returns
2b400 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 zero..**.** ^If
2b410 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2b420 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 BLOB or UTF-16 s
2b430 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 tring then the s
2b440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2b450 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 tes16().** routi
2b460 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
2b470 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
2b480 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 n that BLOB or s
2b490 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
2b4a0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 e result is a UT
2b4b0 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e F-8 string, then
2b4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2b4d0 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 bytes16() conver
2b4e0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2b4f0 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 to UTF-16 and t
2b500 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
2b510 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
2b520 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2b530 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 lt is a numeric
2b540 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 value then sqlit
2b550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2b560 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 6() uses.** [sql
2b570 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
2b580 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 to convert that
2b590 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d value to a UTF-
2b5a0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 16 string and re
2b5b0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d turns.** the num
2b5c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2b5d0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 that string..**
2b5e0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2b5f0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c s NULL, then sql
2b600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2b610 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 s16() returns ze
2b620 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 ro..**.** ^The v
2b630 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
2b640 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
2b650 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a n_bytes()] and .
2b660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2b670 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f mn_bytes16()] do
2b680 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 not include the
2b690 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2b6a0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 s at the end.**
2b6b0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 of the string.
2b6c0 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 ^For clarity: th
2b6d0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
2b6e0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
2b6f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d _column_bytes()]
2b700 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f and [sqlite3_co
2b710 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 lumn_bytes16()]
2b720 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f are the number o
2b730 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 f.** bytes in th
2b740 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 e string, not th
2b750 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
2b760 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 acters..**.** ^S
2b770 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
2b780 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2b790 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c n_text() and sql
2b7a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2b7b0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 16(),.** even em
2b7c0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 pty strings, are
2b7d0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
2b7e0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 minated. ^The r
2b7f0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 eturn.** value f
2b800 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 rom sqlite3_colu
2b810 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 mn_blob() for a
2b820 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 zero-length BLOB
2b830 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2b840 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f er..**.** ^The o
2b850 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
2b860 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
2b870 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e n_value()] is an
2b880 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
2b890 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2b8a0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 object. An unpr
2b8b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2b8c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 value object.**
2b8d0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
2b8e0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 with [sqlite3_b
2b8f0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ind_value()] and
2b900 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
2b910 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 _value()]..** If
2b920 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 the [unprotecte
2b930 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2b940 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
2b950 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
2b960 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
2b970 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f is used in any o
2b980 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 ther way, includ
2b990 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 ing calls.** to
2b9a0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
2b9b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
2b9c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
2b9d0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 lue_text()],.**
2b9e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 or [sqlite3_valu
2b9f0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e e_bytes()], then
2ba00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2ba10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2ba20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
2ba30 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 attempt to conv
2ba40 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 ert the value wh
2ba50 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e ere appropriate.
2ba60 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c ^For.** exampl
2ba70 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e e, if the intern
2ba80 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
2ba90 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 n is FLOAT and a
2baa0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 text result.**
2bab0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 is requested, [s
2bac0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
2bad0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 )] is used inter
2bae0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d nally to perform
2baf0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 the.** conversi
2bb00 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 on automatically
2bb10 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 . ^(The followi
2bb20 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 ng table details
2bb30 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 the conversions
2bb40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 .** that are app
2bb50 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lied:.**.** <blo
2bb60 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
2bb70 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
2bb80 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 * <tr><th> Inter
2bb90 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e nal<br>Type <th>
2bba0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 Requested<br>Ty
2bbb0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 pe <th> Convers
2bbc0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 ion.**.** <tr><t
2bbd0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
2bbe0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2bbf0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c Result is 0.** <
2bc00 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2bc10 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
2bc20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
2bc30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 .0.** <tr><td>
2bc40 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 NULL <td> T
2bc50 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 EXT <td> Resu
2bc60 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 lt is NULL point
2bc70 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
2bc80 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 NULL <td> B
2bc90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 LOB <td> Resu
2bca0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 lt is NULL point
2bcb0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 er.** <tr><td> I
2bcc0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c NTEGER <td> FL
2bcd0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 OAT <td> Conv
2bce0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 ert from integer
2bcf0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 to float.** <tr
2bd00 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
2bd10 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
2bd20 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 d> ASCII renderi
2bd30 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 ng of the intege
2bd40 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
2bd50 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c TEGER <td> BL
2bd60 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 OB <td> Same
2bd70 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 as INTEGER->TEXT
2bd80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
2bd90 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OAT <td> INTEG
2bda0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 ER <td> Conver
2bdb0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 t from float to
2bdc0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
2bdd0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2bde0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2bdf0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
2be00 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a of the float.**
2be10 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2be20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2be30 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 <td> Same as F
2be40 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 LOAT->TEXT.** <t
2be50 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2be60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
2be70 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a td> Use atoi().*
2be80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2be90 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
2bea0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 <td> Use atof
2beb0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
2bec0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 TEXT <td> B
2bed0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 LOB <td> No c
2bee0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 hange.** <tr><td
2bef0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
2bf00 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 INTEGER <td> C
2bf10 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 onvert to TEXT t
2bf20 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a hen use atoi().*
2bf30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2bf40 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
2bf50 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2bf60 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
2bf70 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c atof().** <tr><
2bf80 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
2bf90 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2bfa0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d Add a zero term
2bfb0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 inator if needed
2bfc0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 .** </table>.**
2bfd0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
2bfe0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 **.** The table
2bff0 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 above makes refe
2c000 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 rence to standar
2c010 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 d C library func
2c020 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 tions atoi().**
2c030 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c and atof(). SQL
2c040 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 ite does not rea
2c050 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 lly use these fu
2c060 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 nctions. It has
2c070 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 its.** own equi
2c080 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 valent internal
2c090 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 routines. The a
2c0a0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 toi() and atof()
2c0b0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 names are.** us
2c0c0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 ed in the table
2c0d0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 for brevity and
2c0e0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 because they are
2c0f0 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 familiar to mos
2c100 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 t.** C programme
2c110 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 rs..**.** Note t
2c120 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f hat when type co
2c130 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c nversions occur,
2c140 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
2c150 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 ed by prior.** c
2c160 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
2c170 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 column_blob(), s
2c180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2c190 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 xt(), and/or.**
2c1a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2c1b0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 ext16() may be i
2c1c0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 nvalidated..** T
2c1d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
2c1e0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 and pointer inva
2c1f0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lidations might
2c200 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 occur.** in the
2c210 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a following cases:
2c220 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2c230 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2c240 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f content is a BLO
2c250 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f B and sqlite3_co
2c260 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a lumn_text() or.*
2c270 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
2c280 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
2c290 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 s called. A zer
2c2a0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 o-terminator mig
2c2b0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 ht.** need
2c2c0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 to be added to t
2c2d0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a he string.</li>.
2c2e0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
2c2f0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
2c300 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 TF-8 text and sq
2c310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2c320 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 es16() or.**
2c330 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
2c340 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
2c350 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2c360 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2c370 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2c380 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c TF-16.</li>.** <
2c390 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2c3a0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 content is UTF-1
2c3b0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 6 text and sqlit
2c3c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2c3d0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
2c3e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2c3f0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
2c400 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
2c410 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
2c420 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f to UTF-8.</
2c430 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a li>.** </ul>.**.
2c440 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 ** ^Conversions
2c450 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 between UTF-16be
2c460 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 and UTF-16le ar
2c470 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e e always done in
2c480 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a place and do.**
2c490 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 not invalidate
2c4a0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c a prior pointer,
2c4b0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 though of cours
2c4c0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 e the content of
2c4d0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 the buffer.** t
2c4e0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f hat the prior po
2c4f0 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 inter references
2c500 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 will have been
2c510 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 modified. Other
2c520 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e kinds.** of con
2c530 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 version are done
2c540 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 in place when i
2c550 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 t is possible, b
2c560 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 ut sometimes the
2c570 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 y.** are not pos
2c580 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f sible and in tho
2c590 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 se cases prior p
2c5a0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 ointers are inva
2c5b0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 lidated..**.** T
2c5c0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 he safest and ea
2c5d0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 siest to remembe
2c5e0 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 r policy is to i
2c5f0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
2c600 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
2c610 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
2c620 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ways:.**.** <ul>
2c630 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
2c640 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 _column_text() f
2c650 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
2c660 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2c670 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
2c680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2c690 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ob() followed by
2c6a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c6b0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
2c6c0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
2c6d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c umn_text16() fol
2c6e0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
2c6f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2c700 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a )</li>.** </ul>.
2c710 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 **.** In other w
2c720 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 ords, you should
2c730 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f call sqlite3_co
2c740 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 lumn_text(),.**
2c750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c760 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 lob(), or sqlite
2c770 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2c780 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 ) first to force
2c790 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 the result.** i
2c7a0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 nto the desired
2c7b0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 format, then inv
2c7c0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 oke sqlite3_colu
2c7d0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
2c7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c7f0 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e bytes16() to fin
2c800 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 d the size of th
2c810 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f e result. Do no
2c820 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 t mix calls.** t
2c830 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2c840 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
2c850 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
2c860 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a with calls to.*
2c870 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
2c880 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 _bytes16(), and
2c890 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 do not mix calls
2c8a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2c8b0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 mn_text16().** w
2c8c0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ith calls to sql
2c8d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2c8e0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 s()..**.** ^The
2c8f0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
2c900 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 d are valid unti
2c910 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 l a type convers
2c920 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a ion occurs as.**
2c930 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 described above
2c940 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 , or until [sqli
2c950 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
2c960 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2c970 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2c980 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
2c990 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d alled. ^The mem
2c9a0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 ory space used t
2c9b0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a o hold strings.*
2c9c0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 * and BLOBs is f
2c9d0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c reed automatical
2c9e0 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f ly. Do <b>not</
2c9f0 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e b> pass the poin
2ca00 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a ters returned.**
2ca10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2ca20 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
2ca30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2ca40 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 ], etc. into.**
2ca50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
2ca60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d ..**.** ^(If a m
2ca70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
2ca80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
2ca90 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 ring the evaluat
2caa0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ion of any.** of
2cab0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
2cac0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 a default value
2cad0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
2cae0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
2caf0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 .** is either th
2cb00 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 e integer 0, the
2cb10 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
2cb20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 number 0.0, or a
2cb30 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
2cb40 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 . Subsequent ca
2cb50 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
2cb60 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 errcode()] will
2cb70 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
2cb80 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 E_NOMEM].)^.*/.S
2cb90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2cba0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2cbb0 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 lumn_blob(sqlite
2cbc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2cbd0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
2cbe0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
2cbf0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f n_bytes(sqlite3_
2cc00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2cc10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2cc20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2cc30 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f bytes16(sqlite3_
2cc40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2cc50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 ;.SQLITE_API dou
2cc60 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
2cc70 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
2cc80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2cc90 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
2cca0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
2ccb0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 n_int(sqlite3_st
2ccc0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2ccd0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
2cce0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
2ccf0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 _column_int64(sq
2cd00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2cd10 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
2cd20 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 PI const unsigne
2cd30 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f d char *sqlite3_
2cd40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 column_text(sqli
2cd50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
2cd60 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
2cd70 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
2cd80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2cd90 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2cda0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
2cdb0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2cdc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2cdd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2cde0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
2cdf0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c _API sqlite3_val
2ce00 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ue *sqlite3_colu
2ce10 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 mn_value(sqlite3
2ce20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2ce30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2ce40 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 EF: Destroy A Pr
2ce50 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2ce60 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 Object.**.** ^T
2ce70 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
2ce80 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
2ce90 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
2cea0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
2ceb0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 tatement]..** ^I
2cec0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
2ced0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
2cee0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e the statement en
2cef0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 countered no err
2cf00 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 ors.** or if the
2cf10 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 statement is ne
2cf20 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 ver been evaluat
2cf30 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ed, then sqlite3
2cf40 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 _finalize() retu
2cf50 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b rns.** SQLITE_OK
2cf60 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 . ^If the most
2cf70 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
2cf80 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 n of statement S
2cf90 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a failed, then.**
2cfa0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2cfb0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 e(S) returns the
2cfc0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
2cfd0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ror code] or.**
2cfe0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
2cff0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
2d000 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
2d010 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 ze(S) routine ca
2d020 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
2d030 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a ny point during.
2d040 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c ** the life cycl
2d050 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 e of [prepared s
2d060 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 tatement] S:.**
2d070 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 before statement
2d080 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 S is ever evalu
2d090 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f ated, after.** o
2d0a0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 ne or more calls
2d0b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
2d0c0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 et()], or after
2d0d0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b any call.** to [
2d0e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2d0f0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
2d100 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
2d110 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a statement has.*
2d120 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 * completed exec
2d130 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e ution..**.** ^In
2d140 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 voking sqlite3_f
2d150 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e inalize() on a N
2d160 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 ULL pointer is a
2d170 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
2d180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
2d190 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 cation must fina
2d1a0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 lize every [prep
2d1b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d1c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 in order to avoi
2d1d0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 d.** resource le
2d1e0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 aks. It is a gr
2d1f0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 ievous error for
2d200 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
2d210 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a to try to use.*
2d220 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 * a prepared sta
2d230 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
2d240 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
2d250 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 ed. Any use of
2d260 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 a prepared.** st
2d270 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 atement after it
2d280 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
2d290 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 zed can result i
2d2a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a n undefined and.
2d2b0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 ** undesirable b
2d2c0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 ehavior such as
2d2d0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 segfaults and he
2d2e0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a ap corruption..*
2d2f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2d300 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2d310 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a e(sqlite3_stmt *
2d320 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2d330 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
2d340 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
2d350 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ent Object.**.**
2d360 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
2d370 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
2d380 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
2d390 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2d3a0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
2d3b0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e t back to its in
2d3c0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 itial state, rea
2d3d0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 dy to be re-exec
2d3e0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 uted..** ^Any SQ
2d3f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 L statement vari
2d400 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 ables that had v
2d410 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 alues bound to t
2d420 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 hem using.** the
2d430 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2d440 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 lob | sqlite3_bi
2d450 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 nd_*() API] reta
2d460 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e in their values.
2d470 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 .** Use [sqlite3
2d480 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
2d490 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 )] to reset the
2d4a0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 bindings..**.**
2d4b0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
2d4c0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
2d4d0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 e resets the [pr
2d4e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2d4f0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 ] S.** back to t
2d500 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
2d510 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a its program..**.
2d520 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
2d530 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
2d540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
2d550 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
2d560 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2d570 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c S returned [SQL
2d580 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c ITE_ROW] or [SQL
2d590 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 ITE_DONE],.** or
2d5a0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 if [sqlite3_ste
2d5b0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 p(S)] has never
2d5c0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c before been call
2d5d0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e ed on S,.** then
2d5e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2d5f0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c S)] returns [SQL
2d600 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e ITE_OK]..**.** ^
2d610 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
2d620 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
2d630 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
2d640 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2d650 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
2d660 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f ndicated an erro
2d670 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 r, then.** [sqli
2d680 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 te3_reset(S)] re
2d690 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 turns an appropr
2d6a0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
2d6b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 ]..**.** ^The [s
2d6c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2d6d0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 interface does
2d6e0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
2d6f0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 alues.** of any
2d700 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2d710 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 ob|bindings] on
2d720 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2d730 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 atement] S..*/.S
2d740 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2d750 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 lite3_reset(sqli
2d760 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2d770 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2d780 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 F: Create Or Red
2d790 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 efine SQL Functi
2d7a0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ons.** KEYWORDS:
2d7b0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 {function creat
2d7c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a ion routines}.**
2d7d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c KEYWORDS: {appl
2d7e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2d7f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a SQL function}.**
2d800 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c KEYWORDS: {appl
2d810 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2d820 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a SQL functions}.*
2d830 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 *.** ^These func
2d840 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 tions (collectiv
2d850 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 ely known as "fu
2d860 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
2d870 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 routines").** ar
2d880 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 e used to add SQ
2d890 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
2d8a0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 ggregates or to
2d8b0 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 redefine the beh
2d8c0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 avior.** of exis
2d8d0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f ting SQL functio
2d8e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
2d8f0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 . The only diff
2d900 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a erences between.
2d910 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 ** these routine
2d920 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 s are the text e
2d930 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 ncoding expected
2d940 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f for.** the seco
2d950 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 nd parameter (th
2d960 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 e name of the fu
2d970 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 nction being cre
2d980 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ated).** and the
2d990 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 presence or abs
2d9a0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 ence of a destru
2d9b0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f ctor callback fo
2d9c0 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 r.** the applica
2d9d0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
2d9e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 r..**.** ^The fi
2d9f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
2da00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2da10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 onnection] to wh
2da20 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 ich the SQL.** f
2da30 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 unction is to be
2da40 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 added. ^If an
2da50 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 application uses
2da60 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 more than one d
2da70 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
2da80 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 ction then appli
2da90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2daa0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 QL functions mus
2dab0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f t be added.** to
2dac0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
2dad0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 onnection separa
2dae0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tely..**.** ^The
2daf0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
2db00 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
2db10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2db20 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 n to be created
2db30 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e or.** redefined.
2db40 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 ^The length of
2db50 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d the name is lim
2db60 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 ited to 255 byte
2db70 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 s in a UTF-8.**
2db80 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 representation,
2db90 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 exclusive of the
2dba0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 zero-terminator
2dbb0 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 . ^Note that th
2dbc0 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 e name.** length
2dbd0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 limit is in UTF
2dbe0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 -8 bytes, not ch
2dbf0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 aracters nor UTF
2dc00 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 -16 bytes. .**
2dc10 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 ^Any attempt to
2dc20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f create a functio
2dc30 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 n with a longer
2dc40 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 name.** will res
2dc50 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d ult in [SQLITE_M
2dc60 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 ISUSE] being ret
2dc70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
2dc80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2dc90 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 r (nArg).** is t
2dca0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
2dcb0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 uments that the
2dcc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
2dcd0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b ** aggregate tak
2dce0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 es. ^If this par
2dcf0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 ameter is -1, th
2dd00 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 en the SQL funct
2dd10 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
2dd20 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 ate may take any
2dd30 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
2dd40 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 ents between 0 a
2dd50 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 nd the limit.**
2dd60 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f set by [sqlite3_
2dd70 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c limit]([SQLITE_L
2dd80 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
2dd90 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 G]). If the thi
2dda0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 rd.** parameter
2ddb0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 is less than -1
2ddc0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 or greater than
2ddd0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 127 then the beh
2dde0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 avior is.** unde
2ddf0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2de00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2de10 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 er, eTextRep, sp
2de20 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 ecifies what.**
2de30 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 [SQLITE_UTF8 | t
2de40 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 ext encoding] th
2de50 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 is SQL function
2de60 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 prefers for.** i
2de70 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ts parameters.
2de80 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 Every SQL functi
2de90 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
2dea0 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 n must be able t
2deb0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 o work.** with U
2dec0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 TF-8, UTF-16le,
2ded0 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 or UTF-16be. Bu
2dee0 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 t some implement
2def0 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a ations may be.**
2df00 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 more efficient
2df10 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e with one encodin
2df20 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 g than another.
2df30 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e ^An application
2df40 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 may.** invoke s
2df50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2df60 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 nction() or sqli
2df70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2df80 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 ion16() multiple
2df90 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 .** times with t
2dfa0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
2dfb0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 but with differ
2dfc0 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 ent values of eT
2dfd0 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e extRep..** ^When
2dfe0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
2dff0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
2e000 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 same function a
2e010 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 re available, SQ
2e020 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 Lite.** will pic
2e030 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 k the one that i
2e040 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 nvolves the leas
2e050 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 t amount of data
2e060 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 conversion..**
2e070 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 If there is only
2e080 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d a single implem
2e090 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 entation which d
2e0a0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 oes not care wha
2e0b0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 t text.** encodi
2e0c0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e ng is used, then
2e0d0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
2e0e0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b ment should be [
2e0f0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a SQLITE_ANY]..**.
2e100 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 ** ^(The fifth p
2e110 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 arameter is an a
2e120 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 rbitrary pointer
2e130 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 . The implement
2e140 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 ation of the.**
2e150 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 function can gai
2e160 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 n access to this
2e170 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b pointer using [
2e180 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
2e190 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 a()].)^.**.** ^T
2e1a0 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 he sixth, sevent
2e1b0 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 h and eighth par
2e1c0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 ameters, xFunc,
2e1d0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
2e1e0 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 , are.** pointer
2e1f0 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 s to C-language
2e200 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 functions that i
2e210 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
2e220 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
2e230 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 aggregate. ^A sc
2e240 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f alar SQL functio
2e250 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
2e260 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2e270 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c the xFunc.** cal
2e280 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c lback only; NULL
2e290 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 pointers must b
2e2a0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
2e2b0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
2e2c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
2e2d0 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 ^An aggregate SQ
2e2e0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
2e2f0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
2e300 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a ation of xStep.*
2e310 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 * and xFinal and
2e320 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 NULL pointer mu
2e330 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 st be passed for
2e340 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 xFunc. ^To dele
2e350 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a te an existing.*
2e360 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f * SQL function o
2e370 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 r aggregate, pas
2e380 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 s NULL pointers
2e390 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 for all three fu
2e3a0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 nction.** callba
2e3b0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 cks..**.** ^(If
2e3c0 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 the ninth parame
2e3d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ter to sqlite3_c
2e3e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
2e3f0 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 2() is not NULL,
2e400 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 .** then it is d
2e410 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 estructor for th
2e420 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
2e430 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 ta pointer. .**
2e440 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
2e450 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 s invoked when t
2e460 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 he function is d
2e470 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 eleted, either b
2e480 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c y being.** overl
2e490 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 oaded or when th
2e4a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2e4b0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a ction closes.)^.
2e4c0 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 ** ^The destruct
2e4d0 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b or is also invok
2e4e0 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 ed if the call t
2e4f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 o.** sqlite3_cre
2e500 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
2e510 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 ) fails..** ^Whe
2e520 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 n the destructor
2e530 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 callback of the
2e540 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 tenth parameter
2e550 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a is invoked, it.
2e560 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 ** is passed a s
2e570 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
2e580 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f hich is a copy o
2e590 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
2e5a0 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 n data .** point
2e5b0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 er which was the
2e5c0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
2e5d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 to sqlite3_crea
2e5e0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 te_function_v2()
2e5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 ..**.** ^It is p
2e600 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 ermitted to regi
2e610 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d ster multiple im
2e620 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
2e630 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e the same.** fun
2e640 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 ctions with the
2e650 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 same name but wi
2e660 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 th either differ
2e670 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a ing numbers of.*
2e680 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 * arguments or d
2e690 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 iffering preferr
2e6a0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
2e6b0 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c s. ^SQLite will
2e6c0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c use.** the impl
2e6d0 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 ementation that
2e6e0 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 most closely mat
2e6f0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 ches the way in
2e700 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c which the.** SQL
2e710 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
2e720 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 d. ^A function
2e730 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
2e740 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 ith a non-negati
2e750 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d ve.** nArg param
2e760 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 eter is a better
2e770 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
2e780 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
2e790 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 ation with.** a
2e7a0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 negative nArg.
2e7b0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 ^A function wher
2e7c0 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
2e7d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a text encoding.**
2e7e0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 matches the dat
2e7f0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 abase encoding i
2e800 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 s a better.** ma
2e810 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
2e820 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
2e830 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 coding is differ
2e840 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e ent. .** ^A fun
2e850 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
2e860 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 encoding differe
2e870 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 nce is between U
2e880 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 TF16le and UTF16
2e890 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 be.** is a close
2e8a0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
2e8b0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
2e8c0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
2e8d0 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 rence is.** betw
2e8e0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 een UTF8 and UTF
2e8f0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 16..**.** ^Built
2e900 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 -in functions ma
2e910 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 y be overloaded
2e920 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 by new applicati
2e930 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2e940 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 ions..**.** ^An
2e950 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2e960 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
2e970 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c permitted to cal
2e980 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 l other.** SQLit
2e990 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 e interfaces. H
2e9a0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c owever, such cal
2e9b0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 ls must not.** c
2e9c0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
2e9d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 e connection nor
2e9e0 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 finalize or res
2e9f0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a et the prepared.
2ea00 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 ** statement in
2ea10 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 which the functi
2ea20 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
2ea30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2ea40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2ea50 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 function(. sqli
2ea60 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
2ea70 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
2ea80 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
2ea90 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
2eaa0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
2eab0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
2eac0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2ead0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2eae0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
2eaf0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
2eb00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
2eb10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
2eb20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
2eb30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2eb40 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
2eb50 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2eb60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 e_function16(.
2eb70 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
2eb80 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 onst void *zFunc
2eb90 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
2eba0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
2ebb0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
2ebc0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
2ebd0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
2ebe0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2ebf0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2ec00 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
2ec10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2ec20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2ec30 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
2ec40 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
2ec50 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 xt*).);.SQLITE_A
2ec60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
2ec70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
2ec80 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
2ec90 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
2eca0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
2ecb0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
2ecc0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
2ecd0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
2ece0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
2ecf0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
2ed00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
2ed10 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
2ed20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2ed30 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2ed40 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
2ed50 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
2ed60 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 context*),. voi
2ed70 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
2ed80 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*).);../*.** CA
2ed90 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 PI3REF: Text Enc
2eda0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 odings.**.** The
2edb0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 se constant defi
2edc0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ne integer codes
2edd0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 that represent
2ede0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 the various.** t
2edf0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 ext encodings su
2ee00 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
2ee10 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
2ee20 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 LITE_UTF8
2ee30 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
2ee40 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 LITE_UTF16LE
2ee50 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
2ee60 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 LITE_UTF16BE
2ee70 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
2ee80 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 LITE_UTF16
2ee90 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 4 /* Use
2eea0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2eeb0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
2eec0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 ITE_ANY
2eed0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
2eee0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2eef0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 on only */.#defi
2ef00 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f ne SQLITE_UTF16_
2ef10 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a ALIGNED 8 /*
2ef20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2ef30 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a collation only *
2ef40 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
2ef50 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 F: Deprecated Fu
2ef60 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 nctions.** DEPRE
2ef70 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 CATED.**.** Thes
2ef80 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
2ef90 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 [deprecated]. I
2efa0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 n order to maint
2efb0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ain.** backwards
2efc0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 compatibility w
2efd0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 ith older code,
2efe0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
2eff0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 continue .** to
2f000 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 be supported. H
2f010 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c owever, new appl
2f020 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
2f030 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 avoid.** the use
2f040 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
2f050 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e ons. To help en
2f060 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 courage people t
2f070 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 o avoid.** using
2f080 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
2f090 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 , we are not goi
2f0a0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 ng to tell you w
2f0b0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a hat they do..*/.
2f0c0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f #ifndef SQLITE_O
2f0d0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 MIT_DEPRECATED.S
2f0e0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
2f0f0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
2f100 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
2f110 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f e_count(sqlite3_
2f120 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
2f130 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
2f140 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
2f150 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
2f160 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
2f170 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
2f180 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
2f190 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 ite3_transfer_bi
2f1a0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 ndings(sqlite3_s
2f1b0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 tmt*, sqlite3_st
2f1c0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 mt*);.SQLITE_API
2f1d0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
2f1e0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 ED int sqlite3_g
2f1f0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f lobal_recover(vo
2f200 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
2f210 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
2f220 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 D void sqlite3_t
2f230 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f hread_cleanup(vo
2f240 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
2f250 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
2f260 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 D int sqlite3_me
2f270 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 mory_alarm(void(
2f280 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
2f290 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 _int64,int),void
2f2a0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 *,sqlite3_int64)
2f2b0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 ;.#endif../*.**
2f2c0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
2f2d0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e ing SQL Function
2f2e0 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 Parameter Value
2f2f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 s.**.** The C-la
2f300 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 nguage implement
2f310 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e ation of SQL fun
2f320 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
2f330 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 gates uses.** th
2f340 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 is set of interf
2f350 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ace routines to
2f360 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d access the param
2f370 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a eter values on.*
2f380 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f * the function o
2f390 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a r aggregate..**.
2f3a0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f ** The xFunc (fo
2f3b0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f r scalar functio
2f3c0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f ns) or xStep (fo
2f3d0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 r aggregates) pa
2f3e0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b rameters.** to [
2f3f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2f400 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b unction()] and [
2f410 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2f420 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 unction16()].**
2f430 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 define callbacks
2f440 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
2f450 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2f460 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
2f470 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 ..** The 3rd par
2f480 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 ameter to these
2f490 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 callbacks is an
2f4a0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
2f4b0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 s to.** [protect
2f4c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2f4d0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 ] objects. Ther
2f4e0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 e is one [sqlite
2f4f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2f500 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 for.** each para
2f510 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c meter to the SQL
2f520 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 function. Thes
2f530 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
2f540 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 sed to.** extrac
2f550 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 t values from th
2f560 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
2f570 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a ] objects..**.**
2f580 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2f590 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b work only with [
2f5a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2f5b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
2f5c0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
2f5d0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f to use these ro
2f5e0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e utines on an [un
2f5f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2f600 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 3_value].** obje
2f610 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e ct results in un
2f620 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
2f630 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
2f640 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 outines work jus
2f650 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 t like the corre
2f660 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e sponding [column
2f670 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
2f680 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 s].** except tha
2f690 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 t these routine
2f6a0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 s take a single
2f6b0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2f6c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2f6d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 .** pointer inst
2f6e0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 ead of a [sqlite
2f6f0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 3_stmt*] pointer
2f700 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 and an integer
2f710 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a column number..*
2f720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2f730 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
2f740 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 interface extra
2f750 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 cts a UTF-16 str
2f760 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 ing.** in the na
2f770 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 tive byte-order
2f780 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 of the host mach
2f790 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 ine. ^The.** sq
2f7a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2f7b0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 16be() and sqlit
2f7c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
2f7d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a e() interfaces.*
2f7e0 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 * extract UTF-16
2f7f0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d strings as big-
2f800 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c endian and littl
2f810 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 e-endian respect
2f820 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ively..**.** ^(T
2f830 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
2f840 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 _numeric_type()
2f850 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
2f860 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e ts to apply.** n
2f870 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 umeric affinity
2f880 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 to the value. T
2f890 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 his means that a
2f8a0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 n attempt is.**
2f8b0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 made to convert
2f8c0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 the value to an
2f8d0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 integer or float
2f8e0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a ing point. If.*
2f8f0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 * such a convers
2f900 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 ion is possible
2f910 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 without loss of
2f920 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 information (in
2f930 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 other.** words,
2f940 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 if the value is
2f950 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f a string that lo
2f960 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 oks like a numbe
2f970 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 r).** then the c
2f980 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 onversion is per
2f990 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 formed. Otherwi
2f9a0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e se no conversion
2f9b0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 occurs..** The
2f9c0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
2f9d0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
2f9e0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
2f9f0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a returned.)^.**.*
2fa00 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 * Please pay par
2fa10 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f ticular attentio
2fa20 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 n to the fact th
2fa30 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 at the pointer r
2fa40 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 eturned.** from
2fa50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
2fa60 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
2fa70 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 _value_text()],
2fa80 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 or.** [sqlite3_v
2fa90 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 alue_text16()] c
2faa0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 an be invalidate
2fab0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e d by a subsequen
2fac0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 t call to.** [sq
2fad0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
2fae0 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 s()], [sqlite3_v
2faf0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c alue_bytes16()],
2fb00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2fb10 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
2fb20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2fb30 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 xt16()]..**.** T
2fb40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 hese routines mu
2fb50 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
2fb60 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
2fb70 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 d as.** the SQL
2fb80 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 function that su
2fb90 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 pplied the [sqli
2fba0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 te3_value*] para
2fbb0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 meters..*/.SQLIT
2fbc0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
2fbd0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
2fbe0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c blob(sqlite3_val
2fbf0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
2fc00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c int sqlite3_val
2fc10 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
2fc20 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
2fc30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2fc40 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 _value_bytes16(s
2fc50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2fc60 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c SQLITE_API doubl
2fc70 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
2fc80 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 double(sqlite3_v
2fc90 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
2fca0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 PI int sqlite3_v
2fcb0 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 alue_int(sqlite3
2fcc0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
2fcd0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
2fce0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64 sqlite3_value
2fcf0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 _int64(sqlite3_v
2fd00 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
2fd10 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 PI const unsigne
2fd20 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f d char *sqlite3_
2fd30 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 value_text(sqlit
2fd40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
2fd50 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2fd60 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
2fd70 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
2fd80 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
2fd90 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2fda0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2fdb0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 xt16le(sqlite3_v
2fdc0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
2fdd0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
2fde0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2fdf0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 t16be(sqlite3_va
2fe00 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
2fe10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 I int sqlite3_va
2fe20 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 lue_type(sqlite3
2fe30 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
2fe40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2fe50 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
2fe60 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
2fe70 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
2fe80 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
2fe90 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
2fea0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d Context.**.** Im
2feb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
2fec0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
2fed0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 unctions use thi
2fee0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 s.** routine to
2fef0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
2ff00 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 for storing thei
2ff10 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e r state..**.** ^
2ff20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 The first time t
2ff30 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 he sqlite3_aggre
2ff40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
2ff50 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
2ff60 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 led .** for a pa
2ff70 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 rticular aggrega
2ff80 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c te function, SQL
2ff90 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 ite.** allocates
2ffa0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 N of memory, ze
2ffb0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 roes out that me
2ffc0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e mory, and return
2ffd0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 s a pointer.** t
2ffe0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 o the new memory
2fff0 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 . ^On second and
30000 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
30010 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s to.** sqlite3_
30020 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
30030 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 t() for the same
30040 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
30050 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a ion instance,.**
30060 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 the same buffer
30070 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 is returned. S
30080 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
30090 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f _context() is no
300a0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 rmally.** called
300b0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 once for each i
300c0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 nvocation of the
300d0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 xStep callback
300e0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 and then one.**
300f0 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 last time when t
30100 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 he xFinal callba
30110 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 ck is invoked.
30120 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d ^(When no rows m
30130 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 atch.** an aggre
30140 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 gate query, the
30150 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b xStep() callback
30160 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 of the aggregat
30170 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d e function.** im
30180 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
30190 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 never called and
301a0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c xFinal() is cal
301b0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 led exactly once
301c0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 ..** In those ca
301d0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 ses, sqlite3_agg
301e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
301f0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 might be called
30200 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 for the.** firs
30210 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 t time from with
30220 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a in xFinal().)^.*
30230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
30240 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
30250 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 ext(C,N) routine
30260 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
30270 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a pointer if N is.
30280 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 ** less than or
30290 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 equal to zero or
302a0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
302b0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 ocate error occu
302c0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 rs..**.** ^(The
302d0 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 amount of space
302e0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
302f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
30300 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a ontext(C,N) is.*
30310 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 * determined by
30320 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
30330 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 on first success
30340 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 ful call. Chang
30350 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 ing the.** value
30360 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 of N in subsequ
30370 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ent call to sqli
30380 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
30390 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a ntext() within.*
303a0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 * the same aggre
303b0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e gate function in
303c0 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 stance will not
303d0 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 resize the memor
303e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e y.** allocation.
303f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 )^.**.** ^SQLite
30400 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 automatically f
30410 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 rees the memory
30420 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a allocated by .**
30430 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
30440 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 te_context() whe
30450 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 n the aggregate
30460 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e query concludes.
30470 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
30480 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
30490 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 be a copy of the
304a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
304b0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 text | SQL funct
304c0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 ion context] tha
304d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 t is the first p
304e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
304f0 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e he xStep or xFin
30500 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 al callback rout
30510 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ine that impleme
30520 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 nts the aggregat
30530 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a e.** function..*
30540 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
30550 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
30560 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
30570 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
30580 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 * the aggregate
30590 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
305a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 running..*/.SQLI
305b0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
305c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
305d0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
305e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
305f0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
30600 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
30610 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
30620 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
30630 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 3_user_data() in
30640 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
30650 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
30660 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
30670 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 s the pUserData
30680 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 parameter (the 5
30690 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a th parameter).**
306a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
306b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
306c0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
306d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
306e0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
306f0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
30700 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
30710 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
30720 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
30730 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
30740 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
30750 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
30760 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
30770 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 h.** the applica
30780 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
30790 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
307a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
307b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 void *sqlite3_us
307c0 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f er_data(sqlite3_
307d0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a context*);../*.*
307e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
307f0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
30800 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a For Functions.**
30810 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30820 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
30830 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 le() interface r
30840 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 eturns a copy of
30850 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 .** the pointer
30860 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
30870 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 connection] (th
30880 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 e 1st parameter)
30890 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
308a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
308b0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
308c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
308d0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
308e0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
308f0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
30900 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
30910 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
30920 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ion..*/.SQLITE_A
30930 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 PI sqlite3 *sqli
30940 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
30950 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f andle(sqlite3_co
30960 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
30970 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 CAPI3REF: Functi
30980 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 on Auxiliary Dat
30990 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c a.**.** The foll
309a0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 owing two functi
309b0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 ons may be used
309c0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 by scalar SQL fu
309d0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 nctions to.** as
309e0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 sociate metadata
309f0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 with argument v
30a00 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 alues. If the sa
30a10 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 me value is pass
30a20 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c ed to.** multipl
30a30 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 e invocations of
30a40 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 the same SQL fu
30a50 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 nction during qu
30a60 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 ery execution, u
30a70 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 nder.** some cir
30a80 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 cumstances the a
30a90 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 ssociated metada
30aa0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 ta may be preser
30ab0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a ved. This may.**
30ac0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 be used, for ex
30ad0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 ample, to add a
30ae0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 regular-expressi
30af0 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c on matching scal
30b00 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 ar.** function.
30b10 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 The compiled ver
30b20 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 sion of the regu
30b30 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 lar expression i
30b40 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d s stored as.** m
30b50 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
30b60 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 ed with the SQL
30b70 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
30b80 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
30b90 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 ession.** patter
30ba0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 n. The compiled
30bb0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
30bc0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 ion can be reuse
30bd0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a d on multiple.**
30be0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
30bf0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
30c00 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 n so that the or
30c10 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 iginal pattern s
30c20 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f tring.** does no
30c30 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 t need to be rec
30c40 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 ompiled on each
30c50 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a invocation..**.*
30c60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
30c70 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
30c80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
30c90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
30ca0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f metadata.** asso
30cb0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 ciated by the sq
30cc0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
30cd0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 a() function wit
30ce0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 h the Nth argume
30cf0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 nt.** value to t
30d00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
30d10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
30d20 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 ^If no metadata
30d30 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a has been ever.*
30d40 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 * been set for t
30d50 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 he Nth argument
30d60 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c of the function,
30d70 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 or if the corre
30d80 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 sponding.** func
30d90 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 tion parameter h
30da0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 as changed since
30db0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 the meta-data w
30dc0 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 as set,.** then
30dd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
30de0 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 ata() returns a
30df0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
30e00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30e10 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 _set_auxdata() i
30e20 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 nterface saves t
30e30 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 he metadata.** p
30e40 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 ointed to by its
30e50 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 3rd parameter a
30e60 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 s the metadata f
30e70 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 or the N-th.** a
30e80 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 rgument of the a
30e90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
30ea0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 ed function. Su
30eb0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c bsequent.** call
30ec0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 s to sqlite3_get
30ed0 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 _auxdata() might
30ee0 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 return this dat
30ef0 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 a, if it has.**
30f00 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 not been destroy
30f10 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 ed..** ^If it is
30f20 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 not NULL, SQLit
30f30 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 e will invoke th
30f40 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 e destructor.**
30f50 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 function given b
30f60 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 y the 4th parame
30f70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 ter to sqlite3_s
30f80 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a et_auxdata() on.
30f90 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 ** the metadata
30fa0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 when the corresp
30fb0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 onding function
30fc0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 parameter change
30fd0 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 s.** or when the
30fe0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 SQL statement c
30ff0 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 ompletes, whiche
31000 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e ver comes first.
31010 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 .**.** SQLite is
31020 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 free to call th
31030 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 e destructor and
31040 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f drop metadata o
31050 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 n any.** paramet
31060 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 er of any functi
31070 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 on at any time.
31080 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 ^The only guara
31090 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 ntee is that.**
310a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 the destructor w
310b0 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 ill be called be
310c0 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 fore the metadat
310d0 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a a is dropped..**
310e0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 .** ^(In practic
310f0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 e, metadata is p
31100 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e reserved between
31110 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 function calls
31120 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f for.** expressio
31130 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 ns that are cons
31140 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 tant at compile
31150 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 time. This inclu
31160 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 des literal.** v
31170 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d alues and [param
31180 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 eters].)^.**.**
31190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
311a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
311b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
311c0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
311d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
311e0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 is running..*/.S
311f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
31200 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
31210 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
31220 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 ext*, int N);.SQ
31230 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
31240 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
31250 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
31260 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a t*, int N, void*
31270 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a , void (*)(void*
31280 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ));.../*.** CAPI
31290 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 3REF: Constants
312a0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c Defining Special
312b0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 Destructor Beha
312c0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 vior.**.** These
312d0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c are special val
312e0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 ues for the dest
312f0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 ructor that is p
31300 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a assed in as the.
31310 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e ** final argumen
31320 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 t to routines li
31330 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ke [sqlite3_resu
31340 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 lt_blob()]. ^If
31350 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a the destructor.
31360 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 ** argument is S
31370 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 QLITE_STATIC, it
31380 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
31390 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 content pointer
313a0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 is constant.** a
313b0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 nd will never ch
313c0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e ange. It does n
313d0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 ot need to be de
313e0 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a stroyed. ^The.*
313f0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 * SQLITE_TRANSIE
31400 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 NT value means t
31410 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
31420 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e will likely chan
31430 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 ge in.** the nea
31440 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 r future and tha
31450 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 t SQLite should
31460 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 make its own pri
31470 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 vate copy of.**
31480 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f the content befo
31490 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
314a0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 .** The typedef
314b0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 is necessary to
314c0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 work around prob
314d0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a lems in certain.
314e0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 ** C++ compilers
314f0 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 . See ticket #2
31500 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 191..*/.typedef
31510 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 void (*sqlite3_d
31520 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 estructor_type)(
31530 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 void*);.#define
31540 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 SQLITE_STATIC
31550 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
31560 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a tructor_type)0).
31570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
31580 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c RANSIENT ((sql
31590 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
315a0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 type)-1)../*.**
315b0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e CAPI3REF: Settin
315c0 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 g The Result Of
315d0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a An SQL Function.
315e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
315f0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 ines are used by
31600 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 the xFunc or xF
31610 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 inal callbacks t
31620 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 hat.** implement
31630 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
31640 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 nd aggregates.
31650 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f See.** [sqlite3_
31660 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
31670 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
31680 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
31690 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 6()].** for addi
316a0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
316b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 on..**.** These
316c0 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 functions work v
316d0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 ery much like th
316e0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e e [parameter bin
316f0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a ding] family of.
31700 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 ** functions use
31710 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 d to bind values
31720 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 to host paramet
31730 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 ers in prepared
31740 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 statements..** R
31750 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c efer to the [SQL
31760 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 parameter] docu
31770 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
31780 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
31790 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
317a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
317b0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 blob() interface
317c0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
317d0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
317e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
317f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
31800 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f he BLOB whose co
31810 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 ntent is pointed
31820 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 .** to by the se
31830 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 cond parameter a
31840 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 nd which is N by
31850 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e tes long where N
31860 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 is the.** third
31870 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
31880 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
31890 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 esult_zeroblob()
318a0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 interfaces set
318b0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a the result of.**
318c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
318d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
318e0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 n to be a BLOB c
318f0 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 ontaining all ze
31900 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 ro.** bytes and
31910 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c N bytes in size,
31920 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
31930 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 value of the 2nd
31940 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
31950 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
31960 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 esult_double() i
31970 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
31980 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a e result from.**
31990 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
319a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
319b0 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e to be a floatin
319c0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 g point value sp
319d0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 ecified.** by it
319e0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a s 2nd argument..
319f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
31a00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
31a10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
31a20 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 sult_error16() f
31a30 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 unctions.** caus
31a40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 e the implemente
31a50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 d SQL function t
31a60 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 o throw an excep
31a70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 tion..** ^SQLite
31a80 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 uses the string
31a90 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
31aa0 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 he.** 2nd parame
31ab0 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 ter of sqlite3_r
31ac0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 esult_error() or
31ad0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31ae0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 error16().** as
31af0 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 the text of an e
31b00 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e rror message. ^
31b10 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 SQLite interpret
31b20 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
31b30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 essage string fr
31b40 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
31b50 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 t_error() as UTF
31b60 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 -8. ^SQLite.** i
31b70 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 nterprets the st
31b80 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
31b90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
31ba0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 () as UTF-16 in
31bb0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f native.** byte o
31bc0 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 rder. ^If the t
31bd0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
31be0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
31bf0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 _error().** or s
31c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
31c10 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 ror16() is negat
31c20 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ive then SQLite
31c30 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 takes as the err
31c40 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c or.** message al
31c50 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 l text up throug
31c60 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
31c70 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e character..** ^
31c80 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
31c90 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
31ca0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
31cb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 or.** sqlite3_r
31cc0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
31cd0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 is non-negative
31ce0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
31cf0 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 s that many.** b
31d00 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 ytes (not charac
31d10 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 ters) from the 2
31d20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 nd parameter as
31d30 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
31d40 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 e..** ^The sqlit
31d50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
31d60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
31d70 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
31d80 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 * routines make
31d90 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f a private copy o
31da0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 f the error mess
31db0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a age text before.
31dc0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 ** they return.
31dd0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c Hence, the call
31de0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e ing function can
31df0 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a deallocate or.*
31e00 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 * modify the tex
31e10 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 t after they ret
31e20 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d urn without harm
31e30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
31e40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
31e50 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ode() function c
31e60 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 hanges the error
31e70 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 code.** returne
31e80 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 d by SQLite as a
31e90 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 result of an er
31ea0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f ror in a functio
31eb0 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c n. ^By default,
31ec0 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f .** the error co
31ed0 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 de is SQLITE_ERR
31ee0 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 OR. ^A subseque
31ef0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 nt call to sqlit
31f00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
31f10 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
31f20 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
31f30 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f resets the erro
31f40 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 r code to SQLITE
31f50 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 _ERROR..**.** ^T
31f60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
31f70 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 t_error_toobig()
31f80 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
31f90 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
31fa0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e w an.** error in
31fb0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 dicating that a
31fc0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 string or BLOB i
31fd0 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 s too long to re
31fe0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e present..**.** ^
31ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
32000 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 lt_error_nomem()
32010 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
32020 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
32030 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e w an.** error in
32040 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 dicating that a
32050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
32060 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 n failed..**.**
32070 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
32080 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 ult_int() interf
32090 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
320a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
320b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
320c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
320d0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 to be the 32-bi
320e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
320f0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
32100 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
32110 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ent..** ^The sql
32120 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
32130 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 4() interface se
32140 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ts the return va
32150 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 lue.** of the ap
32160 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
32170 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
32180 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e the 64-bit sign
32190 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 ed integer.** va
321a0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 lue given in the
321b0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
321c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
321d0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 3_result_null()
321e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
321f0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
32200 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
32210 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
32220 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c nction to be NUL
32230 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 L..**.** ^The sq
32240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
32250 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 t(), sqlite3_res
32260 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a ult_text16(),.**
32270 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
32280 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 text16le(), and
32290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
322a0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 ext16be() interf
322b0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 aces.** set the
322c0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
322d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
322e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
322f0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 to be.** a text
32300 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
32310 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 represented as
32320 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 UTF-8, UTF-16 na
32330 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c tive byte order,
32340 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c .** UTF-16 littl
32350 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 e endian, or UTF
32360 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 -16 big endian,
32370 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
32380 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 ^SQLite takes t
32390 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 he text result f
323a0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 rom the applicat
323b0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ion from.** the
323c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
323d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
323e0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
323f0 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 aces..** ^If the
32400 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
32410 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
32420 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
32430 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 faces.** is nega
32440 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 tive, then SQLit
32450 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 e takes result t
32460 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 ext from the 2nd
32470 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 parameter.** th
32480 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
32490 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
324a0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 ** ^If the 3rd p
324b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
324c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
324d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
324e0 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 ** is non-negati
324f0 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 ve, then as many
32500 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
32510 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 acters) of the t
32520 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 ext.** pointed t
32530 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 o by the 2nd par
32540 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e ameter are taken
32550 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 as the applicat
32560 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 ion-defined.** f
32570 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 unction result.
32580 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
32590 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 meter is non-neg
325a0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a ative, then it.*
325b0 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 * must be the by
325c0 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 te offset into t
325d0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 he string where
325e0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 the NUL terminat
325f0 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 or would.** appe
32600 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 ar if the string
32610 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 where NUL termi
32620 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
32630 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
32640 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 cur.** in the st
32650 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f ring at a byte o
32660 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 ffset that is le
32670 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 ss than the valu
32680 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 e of the 3rd.**
32690 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 parameter, then
326a0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
326b0 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 ring will contai
326c0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 n embedded NULs
326d0 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c and the.** resul
326e0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
326f0 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 operating on st
32700 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 rings with embed
32710 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
32720 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 fined..** ^If th
32730 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
32740 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
32750 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
32760 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
32770 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
32780 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
32790 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
327a0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
327b0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
327c0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
327d0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
327e0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
327f0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
32800 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
32810 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 t..** ^If the 4t
32820 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
32830 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
32840 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
32850 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 es or to.** sqli
32860 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
32870 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
32880 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
32890 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
328a0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
328b0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
328c0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
328d0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
328e0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
328f0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 copy the content
32900 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 of the paramete
32910 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 r nor call a des
32920 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 tructor on the c
32930 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 ontent.** when i
32940 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 t has finished u
32950 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
32960 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
32970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
32980 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
32990 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
329a0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
329b0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
329c0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
329d0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ant SQLITE_TRANS
329e0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c IENT.** then SQL
329f0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
32a00 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 of the result i
32a10 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e nto space obtain
32a20 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 ed from.** from
32a30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
32a40 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 )] before it ret
32a50 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
32a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
32a70 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
32a80 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
32a90 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
32aa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
32ab0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
32ac0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e copy the.** [un
32ad0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
32ae0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
32af0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
32b00 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
32b10 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
32b20 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
32b30 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
32b40 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
32b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
32b60 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
32b70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
32b80 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
32b90 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
32ba0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
32bb0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
32bc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
32bd0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
32be0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 hout harm..** ^A
32bf0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
32c00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
32c10 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
32c20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
32c30 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
32c40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
32c50 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
32c60 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
32c70 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
32c80 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
32c90 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
32ca0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
32cb0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
32cc0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
32cd0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
32ce0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
32cf0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
32d00 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
32d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
32d20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
32d30 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
32d40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
32d50 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
32d60 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
32d70 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 defined..*/.SQLI
32d80 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
32d90 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
32da0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
32db0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
32dc0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
32dd0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
32de0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
32df0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ult_double(sqlit
32e00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 e3_context*, dou
32e10 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ble);.SQLITE_API
32e20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
32e30 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 sult_error(sqlit
32e40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
32e50 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a st char*, int);.
32e60 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
32e70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
32e80 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 rror16(sqlite3_c
32e90 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
32ea0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 oid*, int);.SQLI
32eb0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
32ec0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
32ed0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f _toobig(sqlite3_
32ee0 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
32ef0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
32f00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
32f10 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f nomem(sqlite3_co
32f20 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
32f30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
32f40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
32f50 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 de(sqlite3_conte
32f60 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 xt*, int);.SQLIT
32f70 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
32f80 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 e3_result_int(sq
32f90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32fa0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
32fb0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
32fc0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 sult_int64(sqlit
32fd0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
32fe0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c ite3_int64);.SQL
32ff0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
33000 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
33010 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33020 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
33030 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
33040 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f lt_text(sqlite3_
33050 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
33060 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 char*, int, void
33070 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
33080 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
33090 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
330a0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
330b0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
330c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
330d0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
330e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
330f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
33100 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33110 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
33120 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
33130 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 ));.SQLITE_API v
33140 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
33150 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 lt_text16be(sqli
33160 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
33170 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
33180 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
33190 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
331a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
331b0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e alue(sqlite3_con
331c0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 text*, sqlite3_v
331d0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
331e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
331f0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
33200 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33210 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
33220 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e CAPI3REF: Defin
33230 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 e New Collating
33240 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 Sequences.**.**
33250 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
33260 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 add, remove, or
33270 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 modify a [colla
33280 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 tion] associated
33290 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 .** with the [da
332a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
332b0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 n] specified as
332c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
332d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e nt..**.** ^The n
332e0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 ame of the colla
332f0 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 tion is a UTF-8
33300 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 string.** for sq
33310 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
33320 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c lation() and sql
33330 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
33340 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e ation_v2().** an
33350 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e d a UTF-16 strin
33360 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 g in native byte
33370 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 order for sqlit
33380 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
33390 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c ion16()..** ^Col
333a0 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 lation names tha
333b0 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 t compare equal
333c0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 according to [sq
333d0 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 lite3_strnicmp()
333e0 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 ] are.** conside
333f0 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 red to be the sa
33400 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e me name..**.** ^
33410 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d (The third argum
33420 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d ent (eTextRep) m
33430 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 ust be one of th
33440 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 e constants:.**
33450 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
33460 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c LITE_UTF8],.** <
33470 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 li> [SQLITE_UTF1
33480 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 6LE],.** <li> [S
33490 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
334a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
334b0 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c UTF16], or.** <l
334c0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 i> [SQLITE_UTF16
334d0 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f _ALIGNED]..** </
334e0 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 ul>)^.** ^The eT
334f0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 extRep argument
33500 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 determines the e
33510 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e ncoding of strin
33520 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 gs passed.** to
33530 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 the collating fu
33540 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c nction callback,
33550 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e xCallback..** ^
33560 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 The [SQLITE_UTF1
33570 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 6] and [SQLITE_U
33580 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 TF16_ALIGNED] va
33590 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 lues for eTextRe
335a0 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e p.** force strin
335b0 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 gs to be UTF16 w
335c0 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 ith native byte
335d0 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b order..** ^The [
335e0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
335f0 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 GNED] value for
33600 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 eTextRep forces
33610 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e strings to begin
33620 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 .** on an even b
33630 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a yte address..**.
33640 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 ** ^The fourth a
33650 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 rgument, pArg, i
33660 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e s an application
33670 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 data pointer th
33680 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 at is passed.**
33690 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 through as the f
336a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
336b0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
336c0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b unction callback
336d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 ..**.** ^The fif
336e0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 th argument, xCa
336f0 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 llback, is a poi
33700 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c nter to the coll
33710 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a ating function..
33720 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c ** ^Multiple col
33730 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 lating functions
33740 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 can be register
33750 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d ed using the sam
33760 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 e name but.** wi
33770 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 th different eTe
33780 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 xtRep parameters
33790 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c and SQLite will
337a0 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a use whichever.*
337b0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 * function requi
337c0 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d res the least am
337d0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 ount of data tra
337e0 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 nsformation..**
337f0 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 ^If the xCallbac
33800 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 k argument is NU
33810 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c LL then the coll
33820 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 ating function i
33830 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e s.** deleted. ^
33840 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 When all collati
33850 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 ng functions hav
33860 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ing the same nam
33870 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a e are deleted,.*
33880 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e * that collation
33890 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 is no longer us
338a0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
338b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
338c0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ion callback is
338d0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 invoked with a c
338e0 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 opy of the pArg
338f0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
33900 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 data pointer and
33910 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 with two string
33920 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e s in the encodin
33930 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 g specified.** b
33940 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 y the eTextRep a
33950 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f rgument. The co
33960 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
33970 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a must return an.
33980 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 ** integer that
33990 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 is negative, zer
339a0 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a o, or positive.*
339b0 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 * if the first s
339c0 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 tring is less th
339d0 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 an, equal to, or
339e0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
339f0 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 e second,.** res
33a00 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f pectively. A co
33a10 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
33a20 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 must always ret
33a30 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 urn the same ans
33a40 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 wer.** given the
33a50 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 same inputs. I
33a60 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f f two or more co
33a70 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
33a80 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 s are registered
33a90 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 .** to the same
33aa0 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 collation name (
33ab0 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 using different
33ac0 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 eTextRep values)
33ad0 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 then all.** mus
33ae0 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 t give an equiva
33af0 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e lent answer when
33b00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 invoked with eq
33b10 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 uivalent strings
33b20 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 ..** The collati
33b30 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ng function must
33b40 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 obey the follow
33b50 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 ing properties f
33b60 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 or all.** string
33b70 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a s A, B, and C:.*
33b80 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
33b90 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 > If A==B then B
33ba0 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 ==A..** <li> If
33bb0 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 A==B and B==C th
33bc0 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e en A==C..** <li>
33bd0 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 If A<B THEN
33be0 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 B>A..** <li>
33bf0 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 If A<B and B&
33c00 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 lt;C then A<C
33c10 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a ..** </ol>.**.**
33c20 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 If a collating
33c30 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 function fails a
33c40 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 ny of the above
33c50 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 constraints and
33c60 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e that.** collatin
33c70 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 g function is r
33c80 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 egistered and us
33c90 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ed, then the beh
33ca0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a avior of SQLite.
33cb0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ** is undefined.
33cc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
33cd0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
33ce0 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 tion_v2() works
33cf0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 like sqlite3_cre
33d00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a ate_collation().
33d10 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 ** with the addi
33d20 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 tion that the xD
33d30 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 estroy callback
33d40 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 is invoked on pA
33d50 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 rg when.** the c
33d60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
33d70 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a n is deleted..**
33d80 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 ^Collating func
33d90 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 tions are delete
33da0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 d when they are
33db0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 overridden by la
33dc0 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ter.** calls to
33dd0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 the collation cr
33de0 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 eation functions
33df0 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 or when the.**
33e00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
33e10 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 tion] is closed
33e20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
33e30 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e lose()]..**.** ^
33e40 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c The xDestroy cal
33e50 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c lback is <u>not<
33e60 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 /u> called if th
33e70 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 e .** sqlite3_cr
33e80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
33e90 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 2() function fai
33ea0 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ls. Application
33eb0 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a s that invoke.**
33ec0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
33ed0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 collation_v2() w
33ee0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 ith a non-NULL x
33ef0 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 Destroy argument
33f00 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 should .** chec
33f10 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
33f20 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 e and dispose of
33f30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
33f40 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a data pointer.**
33f50 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 themselves rath
33f60 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e er than expectin
33f70 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c g SQLite to deal
33f80 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 with it for the
33f90 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 m..** This is di
33fa0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 fferent from eve
33fb0 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ry other SQLite
33fc0 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
33fd0 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a inconsistency .*
33fe0 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 * is unfortunate
33ff0 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 but cannot be c
34000 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 hanged without b
34010 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 reaking backward
34020 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c s .** compatibil
34030 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ity..**.** See a
34040 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 lso: [sqlite3_c
34050 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
34060 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
34070 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
34080 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 16()]..*/.SQLITE
34090 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
340a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
340b0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a n(. sqlite3*, .
340c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
340d0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
340e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 tRep, . void *p
340f0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d Arg,. int(*xCom
34100 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
34110 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
34120 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
34130 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
34140 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
34150 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 llation_v2(. sq
34160 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
34170 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 char *zName, .
34180 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
34190 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 void *pArg,.
341a0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 int(*xCompare)(v
341b0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
341c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
341d0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 oid*),. void(*x
341e0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a Destroy)(void*).
341f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
34200 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
34210 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 _collation16(.
34220 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
34230 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a st void *zName,.
34240 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
34250 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 . void *pArg,.
34260 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
34270 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
34280 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
34290 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a void*).);../*.**
342a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 CAPI3REF: Colla
342b0 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c tion Needed Call
342c0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 backs.**.** ^To
342d0 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 avoid having to
342e0 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c register all col
342f0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 lation sequences
34300 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 before a databa
34310 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 se.** can be use
34320 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c d, a single call
34330 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 back function ma
34340 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 y be registered
34350 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 with the.** [dat
34360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
34370 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 ] to be invoked
34380 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 whenever an unde
34390 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a fined collation.
343a0 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 ** sequence is r
343b0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e equired..**.** ^
343c0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 If the function
343d0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 is registered us
343e0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
343f0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
34400 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 () API,.** then
34410 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 it is passed the
34420 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 names of undefi
34430 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ned collation se
34440 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e quences as strin
34450 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e gs.** encoded in
34460 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 UTF-8. ^If sqli
34470 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
34480 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 eded16() is used
34490 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 ,.** the names a
344a0 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 re passed as UTF
344b0 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e -16 in machine n
344c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
344d0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 ..** ^A call to
344e0 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 either function
344f0 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 replaces the exi
34500 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d sting collation-
34510 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e needed callback.
34520 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 .**.** ^(When th
34530 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e e callback is in
34540 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 voked, the first
34550 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 argument passed
34560 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 is a copy.** of
34570 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
34580 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
34590 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
345a0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
345b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
345c0 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f d16(). The seco
345d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
345e0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
345f0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 onnection. The
34600 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
34610 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
34620 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f _UTF8], [SQLITE_
34630 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 UTF16BE],.** or
34640 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
34650 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 , indicating the
34660 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 most desirable
34670 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c form of the coll
34680 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 ation.** sequenc
34690 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 e function requi
346a0 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 red. The fourth
346b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
346c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a e name of the.**
346d0 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 required collat
346e0 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a ion sequence.)^.
346f0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 **.** The callba
34700 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 ck function shou
34710 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 ld register the
34720 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f desired collatio
34730 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
34740 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
34750 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 tion()], [sqlite
34760 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
34770 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b on16()], or.** [
34780 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
34790 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a ollation_v2()]..
347a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
347b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 t sqlite3_collat
347c0 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 ion_needed(. sq
347d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a lite3*, . void*
347e0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 , . void(*)(voi
347f0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
34800 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 eTextRep,const c
34810 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f har*).);.SQLITE_
34820 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
34830 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
34840 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
34850 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 . void*,. void
34860 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
34870 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
34880 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
34890 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 .#ifdef SQLITE_H
348a0 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 AS_CODEC./*.** S
348b0 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 pecify the key f
348c0 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 or an encrypted
348d0 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 database. This
348e0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 routine should b
348f0 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 e.** called righ
34900 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f t after sqlite3_
34910 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 open()..**.** Th
34920 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
34930 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
34940 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
34950 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
34960 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
34970 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
34980 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 int sqlite3_key(
34990 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
349a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
349b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f /* Database to
349c0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 be rekeyed */.
349d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 const void *pKe
349e0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 y, int nKey
349f0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b /* The key */.);
34a00 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 ../*.** Change t
34a10 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 he key on an ope
34a20 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 n database. If
34a30 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 the current data
34a40 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 base is not.** e
34a50 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 ncrypted, this r
34a60 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 outine will encr
34a70 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 ypt it. If pNew
34a80 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 ==0 or nNew==0,
34a90 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
34aa0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a is decrypted..**
34ab0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 .** The code to
34ac0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 implement this A
34ad0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 PI is not availa
34ae0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 ble in the publi
34af0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 c release.** of
34b00 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 SQLite..*/.SQLIT
34b10 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
34b20 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 3_rekey(. sqlit
34b30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
34b40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
34b50 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 abase to be reke
34b60 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 yed */. const v
34b70 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e oid *pKey, int n
34b80 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e Key /* The n
34b90 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a ew key */.);../*
34ba0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 .** Specify the
34bb0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 activation key f
34bc0 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 or a SEE databas
34bd0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 e. Unless .** a
34be0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f ctivated, none o
34bf0 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e f the SEE routin
34c00 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f es will work..*/
34c10 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
34c20 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 sqlite3_activat
34c30 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 e_see(. const c
34c40 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 har *zPassPhrase
34c50 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 /* Activ
34c60 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a ation phrase */.
34c70 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 );.#endif..#ifde
34c80 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
34c90 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 CEROD./*.** Spec
34ca0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 ify the activati
34cb0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 on key for a CER
34cc0 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e OD database. Un
34cd0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 less .** activat
34ce0 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 ed, none of the
34cf0 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 CEROD routines w
34d00 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c ill work..*/.SQL
34d10 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
34d20 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 ite3_activate_ce
34d30 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 rod(. const cha
34d40 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 r *zPassPhrase
34d50 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 /* Activat
34d60 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b ion phrase */.);
34d70 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
34d80 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 API3REF: Suspend
34d90 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 Execution For A
34da0 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a Short Time.**.*
34db0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c * The sqlite3_sl
34dc0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 eep() function c
34dd0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e auses the curren
34de0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 t thread to susp
34df0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a end execution.**
34e00 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 for at least a
34e10 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
34e20 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 econds specified
34e30 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 in its paramete
34e40 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 r..**.** If the
34e50 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
34e60 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 does not suppor
34e70 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 t sleep requests
34e80 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 with.** millise
34e90 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 cond time resolu
34ea0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 tion, then the t
34eb0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e ime will be roun
34ec0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 ded up to.** the
34ed0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e nearest second.
34ee0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d The number of m
34ef0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
34f00 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a leep actually.**
34f10 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 requested from
34f20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
34f30 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 stem is returned
34f40 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
34f50 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 implements this
34f60 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c interface by cal
34f70 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 ling the xSleep(
34f80 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 ).** method of t
34f90 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
34fa0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
34fb0 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 If the xSleep(
34fc0 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 ) method.** of t
34fd0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 he default VFS i
34fe0 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 s not implemente
34ff0 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 d correctly, or
35000 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 not implemented
35010 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 at.** all, then
35020 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
35030 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 sqlite3_sleep()
35040 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d may deviate from
35050 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e the description
35060 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 .** in the previ
35070 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a ous paragraphs..
35080 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
35090 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 t sqlite3_sleep(
350a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
350b0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 I3REF: Name Of T
350c0 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e he Folder Holdin
350d0 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 g Temporary File
350e0 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 s.**.** ^(If thi
350f0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c s global variabl
35100 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 e is made to poi
35110 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 nt to a string w
35120 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e hich is.** the n
35130 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 ame of a folder
35140 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 (a.k.a. director
35150 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d y), then all tem
35160 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 porary files.**
35170 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 created by SQLit
35180 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 e when using a b
35190 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 uilt-in [sqlite3
351a0 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 _vfs | VFS].** w
351b0 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e ill be placed in
351c0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e that directory.
351d0 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 )^ ^If this var
351e0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 iable.** is a NU
351f0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
35200 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 SQLite performs
35210 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e a search for an
35220 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 appropriate.**
35230 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 temporary file d
35240 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
35250 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
35260 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 o read or modify
35270 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 this variable i
35280 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a n more than one.
35290 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 ** thread at a t
352a0 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 ime. It is not
352b0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 safe to read or
352c0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 modify this vari
352d0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 able.** if a [da
352e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
352f0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 n] is being used
35300 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
35310 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a e in a separate.
35320 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 ** thread..** It
35330 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 is intended tha
35340 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 t this variable
35350 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 be set once.** a
35360 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 s part of proces
35370 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
35380 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 and before any
35390 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
353a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 .** routines hav
353b0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e e been called an
353c0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 d that this vari
353d0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 able remain unch
353e0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 anged.** thereaf
353f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
35400 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
35410 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 ctory pragma] ma
35420 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 y modify this va
35430 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 riable and cause
35440 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 .** it to point
35450 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
35460 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
35470 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 _malloc]. ^Furt
35480 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 hermore,.** the
35490 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
354a0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c ctory pragma] al
354b0 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 ways assumes tha
354c0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 t any string.**
354d0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
354e0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 le points to is
354f0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f held in memory o
35500 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a btained from .**
35510 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
35520 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 ] and the pragma
35530 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 may attempt to
35540 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 free that memory
35550 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
35560 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e e3_free]..** Hen
35570 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 ce, if this vari
35580 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 able is modified
35590 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 directly, eithe
355a0 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a r it should be.*
355b0 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d * made NULL or m
355c0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
355d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
355e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
355f0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 lloc].** or else
35600 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 the use of the
35610 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
35620 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 ctory pragma] sh
35630 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e ould be avoided.
35640 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
35650 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d o Windows Runtim
35660 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 e users:</b> Th
35670 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 e temporary dire
35680 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 ctory must be se
35690 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 t.** prior to ca
356a0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f lling [sqlite3_o
356b0 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 pen] or [sqlite3
356c0 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 _open_v2]. Othe
356d0 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a rwise, various.*
356e0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 * features that
356f0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 require the use
35700 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c of temporary fil
35710 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 es may fail. He
35720 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d re is an.** exam
35730 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f ple of how to do
35740 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 this using C++
35750 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 with the Windows
35760 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 Runtime:.**.**
35770 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
35780 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 >.** LPCWSTR zPa
35790 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 th = Windows::St
357a0 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 orage::Applicati
357b0 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d onData::Current-
357c0 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 >.**
357d0 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d TemporaryFolder-
357e0 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a >Path->Data();.*
357f0 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 * char zPathBuf&
35800 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 #91;MAX_PATH + 1
35810 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 ];.** memset
35820 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 (zPathBuf, 0, si
35830 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b zeof(zPathBuf));
35840 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 .** WideCharToMu
35850 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c ltiByte(CP_UTF8,
35860 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 0, zPath, -1, z
35870 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 PathBuf, sizeof(
35880 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e zPathBuf),.** &n
35890 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e bsp; NULL, N
358a0 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 ULL);.** sqlite3
358b0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 _temp_directory
358c0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
358d0 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 f("%s", zPathBuf
358e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
358f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c ockquote>.*/.SQL
35900 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 ITE_API SQLITE_E
35910 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 XTERN char *sqli
35920 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f te3_temp_directo
35930 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ry;../*.** CAPI3
35940 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 REF: Name Of The
35950 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 Folder Holding
35960 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a Database Files.*
35970 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 *.** ^(If this g
35980 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 lobal variable i
35990 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
359a0 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 to a string whic
359b0 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 h is.** the name
359c0 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e of a folder (a.
359d0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c k.a. directory),
359e0 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 then all databa
359f0 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 se files.** spec
35a00 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c ified with a rel
35a10 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 ative pathname a
35a20 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 nd created or ac
35a30 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c cessed by.** SQL
35a40 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 ite when using a
35a50 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 built-in window
35a60 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c s [sqlite3_vfs |
35a70 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 VFS] will be as
35a80 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 sumed.** to be r
35a90 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 elative to that
35aa0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 directory.)^ ^If
35ab0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 this variable i
35ac0 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e s a NULL.** poin
35ad0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
35ae0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c assumes that al
35af0 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 l database files
35b00 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 specified.** wi
35b10 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 th a relative pa
35b20 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 thname are relat
35b30 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 ive to the curre
35b40 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 nt directory.**
35b50 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e for the process.
35b60 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f Only the windo
35b70 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 ws VFS makes use
35b80 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a of this global.
35b90 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 ** variable; it
35ba0 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 is ignored by th
35bb0 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a e unix VFS..**.*
35bc0 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 * Changing the v
35bd0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 alue of this var
35be0 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 iable while a da
35bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
35c00 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e n is.** open can
35c10 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 result in a cor
35c20 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a rupt database..*
35c30 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 *.** It is not s
35c40 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d afe to read or m
35c50 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 odify this varia
35c60 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e ble in more than
35c70 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 one.** thread a
35c80 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 t a time. It is
35c90 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 not safe to rea
35ca0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 d or modify this
35cb0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 variable.** if
35cc0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
35cd0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 ection] is being
35ce0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d used at the sam
35cf0 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 e time in a sepa
35d00 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a rate.** thread..
35d10 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 ** It is intende
35d20 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 d that this vari
35d30 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 able be set once
35d40 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 .** as part of p
35d50 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a rocess initializ
35d60 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 ation and before
35d70 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 any SQLite inte
35d80 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 rface.** routine
35d90 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c s have been call
35da0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 ed and that this
35db0 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e variable remain
35dc0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 unchanged.** th
35dd0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 ereafter..**.**
35de0 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 ^The [data_store
35df0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d _directory pragm
35e00 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 a] may modify th
35e10 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 is variable and
35e20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 cause.** it to p
35e30 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
35e40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
35e50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 lite3_malloc].
35e60 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a ^Furthermore,.**
35e70 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 the [data_store
35e80 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d _directory pragm
35e90 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 a] always assume
35ea0 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e s that any strin
35eb0 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 g.** that this v
35ec0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 ariable points t
35ed0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d o is held in mem
35ee0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
35ef0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d m .** [sqlite3_m
35f00 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 alloc] and the p
35f10 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 ragma may attemp
35f20 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d t to free that m
35f30 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b emory.** using [
35f40 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a sqlite3_free]..*
35f50 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 * Hence, if this
35f60 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 variable is mod
35f70 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 ified directly,
35f80 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 either it should
35f90 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c be.** made NULL
35fa0 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e or made to poin
35fb0 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 t to memory obta
35fc0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
35fd0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 e3_malloc].** or
35fe0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 else the use of
35ff0 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 the [data_store
36000 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d _directory pragm
36010 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f a] should be avo
36020 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ided..*/.SQLITE_
36030 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 API SQLITE_EXTER
36040 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f N char *sqlite3_
36050 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a data_directory;.
36060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36070 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 Test For Auto-C
36080 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 ommit Mode.** KE
36090 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d YWORDS: {autocom
360a0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 mit mode}.**.**
360b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
360c0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e _autocommit() in
360d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
360e0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a non-zero or.** z
360f0 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e ero if the given
36100 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
36110 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f tion is or is no
36120 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 t in autocommit
36130 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 mode,.** respect
36140 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d ively. ^Autocom
36150 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 mit mode is on b
36160 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 y default..** ^A
36170 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
36180 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 s disabled by a
36190 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e [BEGIN] statemen
361a0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 t..** ^Autocommi
361b0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 t mode is re-ena
361c0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 bled by a [COMMI
361d0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d T] or [ROLLBACK]
361e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 ..**.** If certa
361f0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f in kinds of erro
36200 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 rs occur on a st
36210 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
36220 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 multi-statement
36230 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 .** transaction
36240 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e (errors includin
36250 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c g [SQLITE_FULL],
36260 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c [SQLITE_IOERR],
36270 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
36280 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 M], [SQLITE_BUSY
36290 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 ], and [SQLITE_I
362a0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 NTERRUPT]) then
362b0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 the.** transacti
362c0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c on might be roll
362d0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
362e0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 cally. The only
362f0 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 way to.** find
36300 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 out whether SQLi
36310 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 te automatically
36320 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 rolled back the
36330 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 transaction aft
36340 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 er.** an error i
36350 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 s to use this fu
36360 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 nction..**.** If
36370 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
36380 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f changes the auto
36390 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 commit status of
363a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
363b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
363c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 e this routine i
363d0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 s running, then
363e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
363f0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 .** is undefined
36400 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
36410 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
36420 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 autocommit(sqlit
36430 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
36440 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 I3REF: Find The
36450 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 Database Handle
36460 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 Of A Prepared St
36470 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 atement.**.** ^T
36480 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 he sqlite3_db_ha
36490 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 ndle interface r
364a0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 eturns the [data
364b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
364c0 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 handle.** to wh
364d0 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 ich a [prepared
364e0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e statement] belon
364f0 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 gs. ^The [datab
36500 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
36510 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
36520 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
36530 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 is the same [da
36540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36550 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 n].** that was t
36560 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
36570 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c t.** to the [sql
36580 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
36590 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 )] call (or its
365a0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 variants) that w
365b0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 as used to.** cr
365c0 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 eate the stateme
365d0 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 nt in the first
365e0 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 place..*/.SQLITE
365f0 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 _API sqlite3 *sq
36600 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 lite3_db_handle(
36610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
36620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36630 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 Return The File
36640 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 name For A Datab
36650 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase Connection.*
36660 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
36670 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 3_db_filename(D,
36680 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 N) interface ret
36690 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
366a0 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 o a filename.**
366b0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
366c0 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f database N of co
366d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 nnection D. ^Th
366e0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
366f0 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 file.** has the
36700 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 name "main". If
36710 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 there is no att
36720 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e ached database N
36730 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 on the database
36740 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 .** connection D
36750 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 , or if database
36760 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 N is a temporar
36770 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 y or in-memory d
36780 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a atabase, then.**
36790 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
367a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
367b0 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 ** ^The filename
367c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
367d0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 s function is th
367e0 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a e output of the.
367f0 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 ** xFullPathname
36800 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b method of the [
36810 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 VFS]. ^In other
36820 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 words, the file
36830 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 name.** will be
36840 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 an absolute path
36850 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 name, even if th
36860 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a e filename used.
36870 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 ** to open the d
36880 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c atabase original
36890 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 ly was a URI or
368a0 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d relative pathnam
368b0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
368c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
368d0 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 ite3_db_filename
368e0 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f (sqlite3 *db, co
368f0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d nst char *zDbNam
36900 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 e);../*.** CAPI3
36910 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 REF: Determine i
36920 66 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20 f a database is
36930 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 read-only.**.**
36940 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f ^The sqlite3_db_
36950 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e readonly(D,N) in
36960 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
36970 31 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 1 if the databas
36980 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 e N.** of connec
36990 74 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f tion D is read-o
369a0 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 nly, 0 if it is
369b0 72 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d read/write, or -
369c0 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 1 if N is not.**
369d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 the name of a d
369e0 61 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 atabase on conne
369f0 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 51 4c 49 ction D..*/.SQLI
36a00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
36a10 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 e3_db_readonly(s
36a20 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 qlite3 *db, cons
36a30 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 t char *zDbName)
36a40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
36a50 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 F: Find the next
36a60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
36a70 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ent.**.** ^This
36a80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
36a90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
36aa0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 he next [prepare
36ab0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 d statement] aft
36ac0 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f er.** pStmt asso
36ad0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
36ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36af0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 tion] pDb. ^If
36b00 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a pStmt is NULL.**
36b10 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 then this inter
36b20 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
36b30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 ointer to the fi
36b40 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 rst prepared sta
36b50 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 tement.** associ
36b60 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 ated with the da
36b70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36b80 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 n pDb. ^If no p
36b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
36ba0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 t.** satisfies t
36bb0 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 he conditions of
36bc0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 this routine, i
36bd0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a t returns NULL..
36be0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 **.** The [datab
36bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
36c00 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 pointer D in a c
36c10 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
36c20 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 e3_next_stmt(D,S
36c30 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f )] must refer to
36c40 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
36c50 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
36c60 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 and in particula
36c70 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 r must not be a
36c80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
36c90 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
36ca0 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 te3_stmt *sqlite
36cb0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 3_next_stmt(sqli
36cc0 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 te3 *pDb, sqlite
36cd0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
36ce0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36cf0 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c Commit And Roll
36d00 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f back Notificatio
36d10 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a n Callbacks.**.*
36d20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
36d30 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 ommit_hook() int
36d40 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
36d50 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 a callback.** f
36d60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e unction to be in
36d70 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
36d80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
36d90 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 [COMMIT | commit
36da0 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 ted]..** ^Any ca
36db0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 llback set by a
36dc0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
36dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f sqlite3_commit_
36de0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 hook().** for th
36df0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
36e00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
36e10 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 erridden..** ^Th
36e20 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 e sqlite3_rollba
36e30 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 ck_hook() interf
36e40 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
36e50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
36e60 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b tion to be invok
36e70 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 ed whenever a tr
36e80 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f ansaction is [RO
36e90 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 LLBACK | rolled
36ea0 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 back]..** ^Any c
36eb0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 allback set by a
36ec0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
36ed0 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 o sqlite3_rollba
36ee0 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 ck_hook().** for
36ef0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
36f00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
36f10 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
36f20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 ^The pArg argume
36f30 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 nt is passed thr
36f40 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c ough to the call
36f50 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 back..** ^If the
36f60 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 callback on a c
36f70 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 ommit hook funct
36f80 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ion returns non-
36f90 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 zero,.** then th
36fa0 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 e commit is conv
36fb0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c erted into a rol
36fc0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 lback..**.** ^Th
36fd0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 e sqlite3_commit
36fe0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 _hook(D,C,P) and
36ff0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 sqlite3_rollbac
37000 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 k_hook(D,C,P) fu
37010 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 nctions.** retur
37020 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 n the P argument
37030 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f from the previo
37040 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 us call of the s
37050 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ame function.**
37060 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 on the same [dat
37070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
37080 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 ] D, or NULL for
37090 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 .** the first ca
370a0 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 ll for each func
370b0 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a tion on D..**.**
370c0 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 The commit and
370d0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 rollback hook ca
370e0 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 llbacks are not
370f0 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 reentrant..** Th
37100 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 e callback imple
37110 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e mentation must n
37120 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
37130 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
37140 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
37150 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
37160 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c invoked the call
37170 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f back. Any actio
37180 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 ns.** to modify
37190 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
371a0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 nection must be
371b0 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
371c0 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 fter the.** comp
371d0 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 letion of the [s
371e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
371f0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
37200 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a ed the commit.**
37210 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f or rollback hoo
37220 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 k in the first p
37230 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 lace..** Note th
37240 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f at running any o
37250 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65 ther SQL stateme
37260 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 nts, including S
37270 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 ELECT statements
37280 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 ,.** or merely c
37290 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
372a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
372b0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
372c0 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a )] will modify.*
372d0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
372e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
372f0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
37300 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
37310 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
37320 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e ^Registering a N
37330 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 ULL function dis
37340 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 ables the callba
37350 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 ck..**.** ^When
37360 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 the commit hook
37370 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 callback routine
37380 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 returns zero, t
37390 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f he [COMMIT].** o
373a0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f peration is allo
373b0 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 wed to continue
373c0 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 normally. ^If t
373d0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a he commit hook.*
373e0 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 * returns non-ze
373f0 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f ro, then the [CO
37400 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 MMIT] is convert
37410 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 ed into a [ROLLB
37420 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f ACK]..** ^The ro
37430 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 llback hook is i
37440 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c nvoked on a roll
37450 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 back that result
37460 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a s from a commit.
37470 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e ** hook returnin
37480 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 g non-zero, just
37490 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 as it would be
374a0 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 with any other r
374b0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e ollback..**.** ^
374c0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
374d0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 of this API, a
374e0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 transaction is s
374f0 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e aid to have been
37500 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 .** rolled back
37510 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 if an explicit "
37520 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d ROLLBACK" statem
37530 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c ent is executed,
37540 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 or.** an error
37550 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 or constraint ca
37560 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 uses an implicit
37570 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 rollback to occ
37580 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c ur..** ^The roll
37590 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 back callback is
375a0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 not invoked if
375b0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
375c0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
375d0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 y rolled back be
375e0 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 cause the databa
375f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
37600 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 closed..**.** S
37610 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
37620 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
37630 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
37640 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
37650 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 d *sqlite3_commi
37660 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c t_hook(sqlite3*,
37670 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
37680 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 void*);.SQLITE_A
37690 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 PI void *sqlite3
376a0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 _rollback_hook(s
376b0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 qlite3*, void(*)
376c0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 (void *), void*)
376d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
376e0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e F: Data Change N
376f0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c otification Call
37700 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 backs.**.** ^The
37710 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
37720 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
37730 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
37740 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
37750 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 * with the [data
37760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
37770 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
37780 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
37790 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b t.** to be invok
377a0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f ed whenever a ro
377b0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e w is updated, in
377c0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
377d0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 d..** ^Any callb
377e0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
377f0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 vious call to th
37800 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 is function.** f
37810 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
37820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
37830 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
37840 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
37850 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
37860 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 ointer to the fu
37870 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 nction to invoke
37880 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 when a.** row i
37890 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 s updated, inser
378a0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a ted or deleted..
378b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
378c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 gument to the ca
378d0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
378e0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 of the third ar
378f0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
37900 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
37910 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f ()..** ^The seco
37920 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 nd callback argu
37930 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
37940 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 SQLITE_INSERT],
37950 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c [SQLITE_DELETE],
37960 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
37970 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e PDATE], dependin
37980 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 g on the operati
37990 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 on that caused t
379a0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 he callback.** t
379b0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a o be invoked..**
379c0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 ^The third and
379d0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 fourth arguments
379e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
379f0 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 contain pointer
37a00 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
37a10 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e base and table n
37a20 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ame containing t
37a30 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e he affected row.
37a40 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 .** ^The final c
37a50 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
37a60 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d r is the [rowid]
37a70 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 of the row..**
37a80 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 ^In the case of
37a90 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 an update, this
37aa0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 is the [rowid] a
37ab0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 fter the update
37ac0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a takes place..**.
37ad0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 ** ^(The update
37ae0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f hook is not invo
37af0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 ked when interna
37b00 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 l system tables
37b10 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 are.** modified
37b20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 (i.e. sqlite_mas
37b30 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 ter and sqlite_s
37b40 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a equence).)^.**.*
37b50 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e * ^In the curren
37b60 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
37b70 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f , the update hoo
37b80 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f k.** is not invo
37b90 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 ked when duplica
37ba0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 tion rows are de
37bb0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 leted because of
37bc0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c an.** [ON CONFL
37bd0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 ICT | ON CONFLIC
37be0 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 T REPLACE] claus
37bf0 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 e. ^Nor is the
37c00 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 update hook.** i
37c10 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 nvoked when rows
37c20 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 are deleted usi
37c30 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 ng the [truncate
37c40 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a optimization]..
37c50 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e ** The exception
37c60 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 s defined in thi
37c70 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 s paragraph migh
37c80 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 t change in a fu
37c90 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
37ca0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
37cb0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b The update hook
37cc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
37cd0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
37ce0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
37cf0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
37d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
37d10 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
37d20 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 e update hook.
37d30 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 Any actions.** t
37d40 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 o modify the dat
37d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
37d60 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 must be deferre
37d70 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 d until after th
37d80 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 e.** completion
37d90 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
37da0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 step()] call tha
37db0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 t triggered the
37dc0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 update hook..**
37dd0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
37de0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
37df0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
37e00 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
37e10 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
37e20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
37e30 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
37e40 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
37e50 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
37e60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
37e70 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 3_update_hook(D,
37e80 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a C,P) function.**
37e90 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 returns the P a
37ea0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 rgument from the
37eb0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a previous call.*
37ec0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 * on the same [d
37ed0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
37ee0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 on] D, or NULL f
37ef0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 or.** the first
37f00 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a call on D..**.**
37f10 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
37f20 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
37f30 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ok()] and [sqlit
37f40 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
37f50 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
37f60 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
37f70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 void *sqlite3_u
37f80 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 pdate_hook(. sq
37f90 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 lite3*, . void(
37fa0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 *)(void *,int ,c
37fb0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 har const *,char
37fc0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 const *,sqlite3
37fd0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a _int64),. void*
37fe0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
37ff0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
38000 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 isable Shared Pa
38010 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 ger Cache.**.**
38020 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 ^(This routine e
38030 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
38040 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f es the sharing o
38050 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
38060 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 ache.** and sche
38070 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ma data structur
38080 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 es between [data
38090 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
380a0 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a | connections].*
380b0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 * to the same da
380c0 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 tabase. Sharing
380d0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 is enabled if th
380e0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 e argument is tr
380f0 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c ue.** and disabl
38100 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
38110 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a nt is false.)^.*
38120 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 *.** ^Cache shar
38130 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 ing is enabled a
38140 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 nd disabled for
38150 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 an entire proces
38160 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 s..** This is a
38170 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c change as of SQL
38180 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
38190 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 0. In prior vers
381a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a ions of SQLite,.
381b0 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 ** sharing was e
381c0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
381d0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 ed for each thre
381e0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a ad separately..*
381f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 *.** ^(The cache
38200 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 sharing mode se
38210 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 t by this interf
38220 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 ace effects all
38230 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 subsequent.** ca
38240 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
38250 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
38260 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 3_open_v2()], an
38270 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 d [sqlite3_open1
38280 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 6()]..** Existin
38290 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 g database conne
382a0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
382b0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 use the sharing
382c0 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 mode.** that was
382d0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 in effect at th
382e0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 e time they were
382f0 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a opened.)^.**.**
38300 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ^(This routine
38310 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
38320 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 OK] if shared ca
38330 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 che was enabled
38340 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 or disabled.** s
38350 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e uccessfully. An
38360 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
38370 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 returned otherw
38380 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 ise.)^.**.** ^Sh
38390 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 ared cache is di
383a0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
383b0 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 t. But this migh
383c0 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 t change in.** f
383d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
383e0 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 f SQLite. Appli
383f0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 cations that car
38400 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a e about shared.*
38410 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 * cache setting
38420 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 should set it ex
38430 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 plicitly..**.**
38440 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 See Also: [SQLi
38450 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 te Shared-Cache
38460 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f Mode].*/.SQLITE_
38470 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
38480 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
38490 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a che(int);../*.**
384a0 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d CAPI3REF: Attem
384b0 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 pt To Free Heap
384c0 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 Memory.**.** ^Th
384d0 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 e sqlite3_releas
384e0 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 e_memory() inter
384f0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
38500 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a free N bytes.**
38510 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 of heap memory
38520 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 by deallocating
38530 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 non-essential me
38540 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
38550 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 .** held by the
38560 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 database library
38570 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 . Memory used
38580 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 to cache databas
38590 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d e.** pages to im
385a0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 prove performanc
385b0 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 e is an example
385c0 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c of non-essential
385d0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c memory..** ^sql
385e0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
385f0 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 ory() returns th
38600 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
38610 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 s actually freed
38620 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 ,.** which might
38630 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 be more or less
38640 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 than the amount
38650 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e requested..** ^
38660 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 The sqlite3_rele
38670 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 ase_memory() rou
38680 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 tine is a no-op
38690 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a returning zero.*
386a0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e * if SQLite is n
386b0 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ot compiled with
386c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
386d0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e MEMORY_MANAGEMEN
386e0 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c T]..**.** See al
386f0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f so: [sqlite3_db_
38700 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
38710 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
38720 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 int sqlite3_rele
38730 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b ase_memory(int);
38740 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
38750 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55 73 : Free Memory Us
38760 65 64 20 42 79 20 41 20 44 61 74 61 62 61 73 65 ed By A Database
38770 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a Connection.**.*
38780 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
38790 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 b_release_memory
387a0 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 (D) interface at
387b0 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61 tempts to free a
387c0 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d s much heap.** m
387d