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 30 22 0a 23 64 65 66 69 6e 65 20 53 .7.10".#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 30 0a 23 64 65 MBER 3007010.#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 31 2d 31 36 20 31 33 3a 32 38 3a 34 30 20 -01-16 13:28:40
1080: 65 62 64 30 31 61 38 64 65 66 66 62 35 30 32 34 ebd01a8deffb5024
1090: 61 35 64 37 34 39 34 65 65 66 38 30 30 64 32 33 a5d7494eef800d23
10a0: 36 36 64 39 37 32 30 34 22 0a 0a 2f 2a 0a 2a 2a 66d97204"../*.**
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 69 73 20 _close()].** is
2490: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20 its destructor.
24a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 There are many
24b0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 other interfaces
24c0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 (such as.** [sq
24d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
24e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
24f0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
2510: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
2520: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 ] to name but th
2530: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 ree) that are me
2540: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 thods on an.** s
2550: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a qlite3 object..*
2560: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
2570: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 sqlite3 sqlite3
2580: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2590: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 F: 64-Bit Intege
25a0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f r Types.** KEYWO
25b0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 RDS: sqlite_int6
25c0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 4 sqlite_uint64.
25d0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 **.** Because th
25e0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d ere is no cross-
25f0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 platform way to
2600: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 specify 64-bit i
2610: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 nteger types.**
2620: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 SQLite includes
2630: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d typedefs for 64-
2640: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 bit signed and u
2650: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 nsigned integers
2660: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
2670: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
2680: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 lite3_uint64 are
2690: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 the preferred t
26a0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e ype definitions.
26b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 .** The sqlite_i
26c0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
26d0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 uint64 types are
26e0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 supported for b
26f0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
2700: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a atibility only..
2710: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2720: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
2730: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 ite_int64 types
2740: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 can store intege
2750: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 r values.** betw
2760: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 een -92233720368
2770: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 54775808 and +92
2780: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 2337203685477580
2790: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 7 inclusive. ^T
27a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 he.** sqlite3_ui
27b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
27c0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e uint64 types can
27d0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 store integer v
27e0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 alues .** betwee
27f0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 n 0 and +1844674
2800: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 4073709551615 in
2810: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 clusive..*/.#ifd
2820: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ef SQLITE_INT64_
2830: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 TYPE. typedef S
2840: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
2850: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2860: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2870: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 d SQLITE_INT64_T
2880: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 YPE sqlite_uint6
2890: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 4;.#elif defined
28a0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 (_MSC_VER) || de
28b0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 fined(__BORLANDC
28c0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f __). typedef __
28d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 int64 sqlite_int
28e0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
28f0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 signed __int64 s
2900: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
2910: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f lse. typedef lo
2920: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
2930: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
2940: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e def unsigned lon
2950: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
2960: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 e_uint64;.#endif
2970: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
2980: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e int64 sqlite3_in
2990: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c t64;.typedef sql
29a0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 ite_uint64 sqlit
29b0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a e3_uint64;../*.*
29c0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 * If compiling f
29d0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 or a processor t
29e0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 hat lacks floati
29f0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 ng point support
2a00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 ,.** substitute
2a10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 integer for floa
2a20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 ting-point..*/.#
2a30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 ifdef SQLITE_OMI
2a40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 T_FLOATING_POINT
2a50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 .# define double
2a60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 sqlite3_int64.#
2a70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
2a80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 I3REF: Closing A
2a90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
2aa0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tion.**.** ^The
2ab0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
2ac0: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 routine is the d
2ad0: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 estructor for th
2ae0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
2af0: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f ct..** ^Calls to
2b00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2b10: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
2b20: 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 K if the [sqlite
2b30: 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 3] object is.**
2b40: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 successfully des
2b50: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 troyed and all a
2b60: 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72 ssociated resour
2b70: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 ces are dealloca
2b80: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 ted..**.** Appli
2b90: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71 cations must [sq
2ba0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
2bb0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b finalize] all [
2bc0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2bd0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c nts].** and [sql
2be0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
2bf0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c | close] all [BL
2c00: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f OB handles] asso
2c10: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 ciated with.** t
2c20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
2c30: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 ect prior to att
2c40: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 empting to close
2c50: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 the object. ^I
2c60: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f f.** sqlite3_clo
2c70: 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f se() is called o
2c80: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f n a [database co
2c90: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 nnection] that s
2ca0: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 till has.** outs
2cb0: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 tanding [prepare
2cc0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72 d statements] or
2cd0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
2ce0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 then it returns
2cf0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e .** SQLITE_BUSY.
2d00: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 .**.** ^If [sqli
2d10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 te3_close()] is
2d20: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 invoked while a
2d30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
2d40: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
2d50: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
2d60: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
2d70: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
2d80: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
2d90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
2da0: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 ] must be either
2db0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
2dc0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 er or an [sqlite
2dd0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 3] object pointe
2de0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 r obtained.** fr
2df0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e om [sqlite3_open
2e00: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2e10: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b en16()], or.** [
2e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2e30: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 )], and not prev
2e40: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a iously closed..*
2e50: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
2e60: 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20 e3_close() with
2e70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 a NULL pointer a
2e80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a rgument is a .**
2e90: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
2ea0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2eb0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nt sqlite3_close
2ec0: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a (sqlite3 *);../*
2ed0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 .** The type for
2ee0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
2ef0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 tion..** This is
2f00: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 legacy and depr
2f10: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 ecated. It is i
2f20: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 ncluded for hist
2f30: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 orical.** compat
2f40: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e ibility and is n
2f50: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a ot documented..*
2f60: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a /.typedef int (*
2f70: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b sqlite3_callback
2f80: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 )(void*,int,char
2f90: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a **, char**);../*
2fa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
2fb0: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 e-Step Query Exe
2fc0: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 cution Interface
2fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2fe0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 e3_exec() interf
2ff0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 ace is a conveni
3000: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f ence wrapper aro
3010: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
3020: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
3030: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
3040: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 and [sqlite3_fi
3050: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 nalize()],.** th
3060: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 at allows an app
3070: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 lication to run
3080: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 multiple stateme
3090: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 nts of SQL.** wi
30a0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 thout having to
30b0: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 use a lot of C c
30c0: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode. .**.** ^The
30d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
30e0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a interface runs z
30f0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d ero or more UTF-
3100: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 8 encoded,.** se
3110: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 micolon-separate
3120: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3130: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 passed into its
3140: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 2nd argument,.**
3150: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 in the context
3160: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
3170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 connection] pas
3180: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 sed in as its 1s
3190: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 t.** argument.
31a0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
31b0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 function of the
31c0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 3rd argument to
31d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
31e0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 () is not NULL,
31f0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b then it is invok
3200: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 ed for each resu
3210: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 lt row.** coming
3220: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c out of the eval
3230: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d uated SQL statem
3240: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 ents. ^The 4th
3250: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 argument to.** s
3260: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3270: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 relayed through
3280: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 to the 1st argu
3290: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 ment of each.**
32a0: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 callback invocat
32b0: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 ion. ^If the ca
32c0: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 llback pointer t
32d0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
32e0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 .** is NULL, the
32f0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 n no callback is
3300: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e ever invoked an
3310: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 d result rows ar
3320: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a e.** ignored..**
3330: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 .** ^If an error
3340: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 occurs while ev
3350: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c aluating the SQL
3360: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 statements pass
3370: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 ed into.** sqlit
3380: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 e3_exec(), then
3390: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 execution of the
33a0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 current stateme
33b0: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 nt stops and.**
33c0: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 subsequent state
33d0: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 ments are skippe
33e0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 d. ^If the 5th
33f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
3400: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 ite3_exec().** i
3410: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 s not NULL then
3420: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
3430: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 e is written int
3440: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
3450: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
3460: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 e3_malloc()] and
3470: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 passed back thr
3480: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 ough the 5th par
3490: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 ameter..** To av
34a0: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 oid memory leaks
34b0: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
34c0: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 n should invoke
34d0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
34e0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 .** on error mes
34f0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 sage strings ret
3500: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 urned through th
3510: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
3520: 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 of.** of sqlite3
3530: 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 _exec() after th
3540: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
3550: 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e string is no lon
3560: 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e ger needed..** ^
3570: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d If the 5th param
3580: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
3590: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 exec() is not NU
35a0: 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 LL and no errors
35b0: 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 .** occur, then
35c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 sqlite3_exec() s
35d0: 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 ets the pointer
35e0: 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d in its 5th param
35f0: 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 eter to.** NULL
3600: 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 before returning
3610: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 ..**.** ^If an s
3620: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
3630: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
3640: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c on-zero, the sql
3650: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 ite3_exec().** r
3660: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 outine returns S
3670: 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 QLITE_ABORT with
3680: 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 out invoking the
3690: 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 callback again
36a0: 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 and.** without r
36b0: 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 unning any subse
36c0: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d quent SQL statem
36d0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ents..**.** ^The
36e0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 2nd argument to
36f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 the sqlite3_exe
3700: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e c() callback fun
3710: 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 ction is the.**
3720: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
3730: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e s in the result.
3740: 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d ^The 3rd argum
3750: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
3760: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c e3_exec().** cal
3770: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 lback is an arra
3780: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
3790: 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 strings obtaine
37a0: 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 d as if from.**
37b0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
37c0: 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 text()], one for
37d0: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e each column. ^
37e0: 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 If an element of
37f0: 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 a.** result row
3800: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 is NULL then th
3810: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
3820: 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 string pointer f
3830: 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 or the.** sqlite
3840: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 3_exec() callbac
3850: 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e k is a NULL poin
3860: 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 ter. ^The 4th a
3870: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a rgument to the.*
3880: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 * sqlite3_exec()
3890: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
38a0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
38b0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 s to strings whe
38c0: 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 re each.** entry
38d0: 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 represents the
38e0: 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f name of correspo
38f0: 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c nding result col
3900: 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a umn as obtained.
3910: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
3920: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e _column_name()].
3930: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 .**.** ^If the 2
3940: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
3950: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3960: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
3970: 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 , a pointer.** t
3980: 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e o an empty strin
3990: 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 g, or a pointer
39a0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e that contains on
39b0: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e ly whitespace an
39c0: 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d d/or .** SQL com
39d0: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 ments, then no S
39e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
39f0: 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 e evaluated and
3a00: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
3a10: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a is not changed..
3a20: 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f **.** Restrictio
3a30: 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ns:.**.** <ul>.*
3a40: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 * <li> The appli
3a50: 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 cation must insu
3a60: 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 re that the 1st
3a70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
3a80: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 ite3_exec().**
3a90: 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 is a valid a
3aa0: 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 nd open [databas
3ab0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
3ac0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 * <li> The appli
3ad0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
3ae0: 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 close [database
3af0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
3b00: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 ified by.**
3b10: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 the 1st paramet
3b20: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3b30: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 ec() while sqlit
3b40: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e e3_exec() is run
3b50: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 ning..** <li> Th
3b60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
3b70: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 st not modify th
3b80: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
3b90: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f text passed into
3ba0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 .** the 2nd
3bb0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 parameter of sq
3bc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 lite3_exec() whi
3bd0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 le sqlite3_exec(
3be0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a ) is running..**
3bf0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 </ul>.*/.SQLITE
3c00: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
3c10: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
3c20: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c40: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
3c50: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
3c60: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c80: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
3c90: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
3ca0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 /. int (*callba
3cb0: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
3cc0: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f ar**,char**), /
3cd0: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
3ce0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ion */. void *,
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3d10: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d /* 1st argum
3d20: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 ent to callback
3d30: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
3d40: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 sg
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3d60: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
3d70: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
3d80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3d90: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
3da0: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 KEYWORDS: SQLIT
3db0: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 E_OK {error code
3dc0: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a } {error codes}.
3dd0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 ** KEYWORDS: {re
3de0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 sult code} {resu
3df0: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 lt codes}.**.**
3e00: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 Many SQLite func
3e10: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 tions return an
3e20: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 integer result c
3e30: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 ode from the set
3e40: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 shown.** here i
3e50: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 n order to indic
3e60: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 ate success or f
3e70: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
3e80: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
3e90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
3ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
3eb0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
3ec0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
3ed0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
3ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
3ef0: 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 des],.** [sqlite
3f00: 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 3_vtab_on_confli
3f10: 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f ct()] [SQLITE_RO
3f20: 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 LLBACK | result
3f30: 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 codes]..*/.#defi
3f40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 ne SQLITE_OK
3f50: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 0 /* Su
3f60: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 ccessful result
3f70: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d */./* beginning-
3f80: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
3f90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3fa0: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 _ERROR 1
3fb0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f /* SQL error o
3fc0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 r missing databa
3fd0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 se */.#define SQ
3fe0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 LITE_INTERNAL
3ff0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 2 /* Interna
4000: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e l logic error in
4010: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 SQLite */.#defi
4020: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 ne SQLITE_PERM
4030: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 3 /* Ac
4040: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 cess permission
4050: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
4060: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 e SQLITE_ABORT
4070: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 4 /* Cal
4080: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 lback routine re
4090: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 quested an abort
40a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
40b0: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 TE_BUSY
40c0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 5 /* The datab
40d0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b ase file is lock
40e0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
40f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 LITE_LOCKED
4100: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 6 /* A table
4110: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 in the database
4120: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 is locked */.#d
4130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d efine SQLITE_NOM
4140: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a EM 7 /*
4150: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c A malloc() fail
4160: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4170: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 LITE_READONLY
4180: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 8 /* Attempt
4190: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 to write a read
41a0: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f only database */
41b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
41c0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 INTERRUPT 9
41d0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 /* Operation te
41e0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 rminated by sqli
41f0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a te3_interrupt()*
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4210: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 _IOERR 10
4220: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f /* Some kind o
4230: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 f disk I/O error
4240: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 occurred */.#de
4250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
4260: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 UPT 11 /*
4270: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 The database dis
4280: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f k image is malfo
4290: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rmed */.#define
42a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
42b0: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 12 /* Unkno
42c0: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c wn opcode in sql
42d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
42e0: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 l() */.#define S
42f0: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 QLITE_FULL
4300: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 13 /* Insert
4310: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 ion failed becau
4320: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 se database is f
4330: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ull */.#define S
4340: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 QLITE_CANTOPEN
4350: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 14 /* Unable
4360: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 to open the dat
4370: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 abase file */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f efine SQLITE_PRO
4390: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a TOCOL 15 /*
43a0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 Database lock p
43b0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f rotocol error */
43c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
43d0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 EMPTY 16
43e0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 /* Database is
43f0: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 empty */.#define
4400: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 SQLITE_SCHEMA
4410: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 17 /* The
4420: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
4430: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 changed */.#defi
4440: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 ne SQLITE_TOOBIG
4450: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 18 /* St
4460: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 ring or BLOB exc
4470: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 eeds size limit
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4490: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 E_CONSTRAINT 19
44a0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 /* Abort due
44b0: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 to constraint vi
44c0: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 olation */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 ne SQLITE_MISMAT
44e0: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 CH 20 /* Da
44f0: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 ta type mismatch
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4510: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 TE_MISUSE 2
4520: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 1 /* Library u
4530: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 sed incorrectly
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4550: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 E_NOLFS 22
4560: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 /* Uses OS fe
4570: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f atures not suppo
4580: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a rted on host */.
4590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
45a0: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 UTH 23
45b0: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e /* Authorization
45c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
45d0: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 ne SQLITE_FORMAT
45e0: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 24 /* Au
45f0: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 xiliary database
4600: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f format error */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4620: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 RANGE 25
4630: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 /* 2nd paramete
4640: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
4650: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a d out of range *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4670: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 _NOTADB 26
4680: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 /* File opened
4690: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 that is not a d
46a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
46c0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 OW 100
46d0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
46e0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f ) has another ro
46f0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 w ready */.#defi
4700: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 ne SQLITE_DONE
4710: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 101 /* sq
4720: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
4730: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
4740: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 ing */./* end-of
4750: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
4770: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
4780: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
4790: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 DS: {extended er
47a0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e ror code} {exten
47b0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d ded error codes}
47c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
47d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
47e0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 ode} {extended r
47f0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a esult codes}.**.
4800: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c ** In its defaul
4810: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c t configuration,
4820: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 SQLite API rout
4830: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 ines return one
4840: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a of 26 integer.**
4850: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 [SQLITE_OK | re
4860: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f sult codes]. Ho
4870: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 wever, experienc
4880: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 e has shown that
4890: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 many of.** thes
48a0: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 e result codes a
48b0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 re too coarse-gr
48c0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 ained. They do
48d0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a not provide as.*
48e0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 * much informati
48f0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d on about problem
4900: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 s as programmers
4910: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e might like. In
4920: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a an effort to.**
4930: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e address this, n
4940: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 ewer versions of
4950: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e SQLite (version
4960: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 3.3.8 and later
4970: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 ) include.** sup
4980: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f port for additio
4990: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 nal result codes
49a0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f that provide mo
49b0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f re detailed info
49c0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
49d0: 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 errors. The ext
49e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
49f0: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f es are enabled o
4a00: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e r disabled.** on
4a10: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 a per database
4a20: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
4a30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
4a40: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
4a50: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 result_codes()]
4a60: 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 API..**.** Some
4a70: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 of the available
4a80: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
4a90: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 codes are liste
4aa0: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d d here..** One m
4ab0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 ay expect the nu
4ac0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 mber of extended
4ad0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 result codes wi
4ae0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 ll be expand.**
4af0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 over time. Soft
4b00: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 ware that uses e
4b10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4b20: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 odes should expe
4b30: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 ct.** to see new
4b40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e result codes in
4b50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
4b60: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
4b70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 * The SQLITE_OK
4b80: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c result code will
4b90: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 never be extend
4ba0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 ed. It will alw
4bb0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c ays.** be exactl
4bc0: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 y zero..*/.#defi
4bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
4be0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
4bf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
4c00: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
4c10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
4c20: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 HORT_READ
4c30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4c40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
4c50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 SQLITE_IOERR_WR
4c60: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ITE
4c70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4c80: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
4c90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 SQLITE_IOERR_FSY
4ca0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 NC (
4cb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4cc0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
4cd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f QLITE_IOERR_DIR_
4ce0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 FSYNC (S
4cf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 QLITE_IOERR | (5
4d00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
4d10: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 LITE_IOERR_TRUNC
4d20: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 ATE (SQ
4d30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c LITE_IOERR | (6<
4d40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4d50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 ITE_IOERR_FSTAT
4d60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4d70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c ITE_IOERR | (7<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 TE_IOERR_UNLOCK
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 TE_IOERR | (8<<8
4dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4dd0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 E_IOERR_RDLOCK
4de0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4df0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 E_IOERR | (9<<8)
4e00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4e10: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 _IOERR_DELETE
4e20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4e30: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 _IOERR | (10<<8)
4e40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4e50: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 _IOERR_BLOCKED
4e60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4e70: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 _IOERR | (11<<8)
4e80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4e90: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 _IOERR_NOMEM
4ea0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4eb0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 _IOERR | (12<<8)
4ec0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4ed0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 _IOERR_ACCESS
4ee0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4ef0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 _IOERR | (13<<8)
4f00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4f10: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 _IOERR_CHECKRESE
4f20: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 RVEDLOCK (SQLITE
4f30: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 _IOERR | (14<<8)
4f40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4f50: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 _IOERR_LOCK
4f60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4f70: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 _IOERR | (15<<8)
4f80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4f90: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 _IOERR_CLOSE
4fa0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4fb0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 _IOERR | (16<<8)
4fc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4fd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 _IOERR_DIR_CLOSE
4fe0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4ff0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 _IOERR | (17<<8)
5000: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5010: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 _IOERR_SHMOPEN
5020: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5030: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 _IOERR | (18<<8)
5040: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5050: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 _IOERR_SHMSIZE
5060: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5070: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 _IOERR | (19<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 _IOERR_SHMLOCK
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 _IOERR | (20<<8)
50c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
50d0: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 _IOERR_SHMMAP
50e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
50f0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 _IOERR | (21<<8)
5100: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5110: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 _IOERR_SEEK
5120: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5130: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 _IOERR | (22<<8)
5140: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5150: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 _LOCKED_SHAREDCA
5160: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 CHE (SQLITE
5170: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 _LOCKED | (1<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5190: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 E_BUSY_RECOVERY
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
51b0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c E_BUSY | (1<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
51d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 TE_CANTOPEN_NOTE
51e0: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 MPDIR (SQLI
51f0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 TE_CANTOPEN | (1
5200: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5210: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 LITE_CORRUPT_VTA
5220: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 B (SQ
5230: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 LITE_CORRUPT | (
5240: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5250: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 QLITE_READONLY_R
5260: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 ECOVERY (S
5270: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
5280: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5290: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
52a0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 _CANTLOCK
52b0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 (SQLITE_READONLY
52c0: 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a | (2<<8))../*.*
52d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
52e0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 s For File Open
52f0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Operations.**.**
5300: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 These bit value
5310: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
5320: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a or use in the.**
5330: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
5340: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f o the [sqlite3_o
5350: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
5360: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 ace and.** in th
5370: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
5380: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
5390: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f vfs.xOpen] metho
53a0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d..*/.#define SQ
53b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
53c0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 LY 0x000
53d0: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 00001 /* Ok for
53e0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
53f0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
5400: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
5410: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 ITE 0x000
5420: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 00002 /* Ok for
5430: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
5440: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
5450: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
5460: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
5470: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 00004 /* Ok for
5480: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
5490: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
54a0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
54b0: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 ONCLOSE 0x000
54c0: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 00008 /* VFS on
54d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
54e0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
54f0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 IVE 0x000
5500: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00010 /* VFS on
5510: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
5520: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 LITE_OPEN_AUTOPR
5530: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 OXY 0x000
5540: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00020 /* VFS on
5550: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
5560: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 LITE_OPEN_URI
5570: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
5580: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 00040 /* Ok for
5590: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
55a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
55b0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
55c0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 B 0x000
55d0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00100 /* VFS on
55e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
55f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
5600: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 B 0x000
5610: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00200 /* VFS on
5620: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
5630: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
5640: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 ENT_DB 0x000
5650: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00400 /* VFS on
5660: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
5670: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a LITE_OPEN_MAIN_J
5680: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 OURNAL 0x000
5690: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00800 /* VFS on
56a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
56b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
56c0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 OURNAL 0x000
56d0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 01000 /* VFS on
56e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
56f0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
5700: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 RNAL 0x000
5710: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 02000 /* VFS on
5720: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
5730: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 LITE_OPEN_MASTER
5740: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 _JOURNAL 0x000
5750: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 04000 /* VFS on
5760: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
5770: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
5780: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 X 0x000
5790: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 08000 /* Ok for
57a0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
57b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
57c0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
57d0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 TEX 0x000
57e0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 10000 /* Ok for
57f0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
5800: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
5810: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
5820: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 CACHE 0x000
5830: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20000 /* Ok for
5840: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
5850: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
5860: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
5870: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 ECACHE 0x000
5880: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 40000 /* Ok for
5890: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
58a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
58b0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 LITE_OPEN_WAL
58c0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
58d0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 80000 /* VFS on
58e0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 ly */../* Reserv
58f0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 ed:
5900: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5910: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a F00000 */../*.**
5920: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 CAPI3REF: Devic
5930: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 e Characteristic
5940: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 s.**.** The xDev
5950: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
5960: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 cs method of the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 hods].** object
5990: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
59a0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 er which is a ve
59b0: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 ctor of the thes
59c0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 e.** bit values
59d0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 expressing I/O c
59e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f haracteristics o
59f0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 f the mass stora
5a00: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 ge.** device tha
5a10: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 t holds the file
5a20: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 that the [sqlit
5a30: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
5a40: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a * refers to..**.
5a50: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f ** The SQLITE_IO
5a60: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 CAP_ATOMIC prope
5a70: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 rty means that a
5a80: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 ll writes of.**
5a90: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f any size are ato
5aa0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
5ab0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e _IOCAP_ATOMICnnn
5ac0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 values.** mean
5ad0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 that writes of b
5ae0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e locks that are n
5af0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 nn bytes in size
5b00: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 and.** are alig
5b10: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 ned to an addres
5b20: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e s which is an in
5b30: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f teger multiple o
5b40: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f f.** nnn are ato
5b50: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
5b60: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
5b70: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a ND value means.*
5b80: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 * that when data
5b90: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 is appended to
5ba0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 a file, the data
5bb0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 is appended.**
5bc0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 first then the s
5bd0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ize of the file
5be0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 is extended, nev
5bf0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 er the other.**
5c00: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 way around. The
5c10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
5c20: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 QUENTIAL propert
5c30: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
5c40: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 information is w
5c50: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 ritten to disk i
5c60: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 n the same order
5c70: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 as calls.** to
5c80: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 xWrite(). The S
5c90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
5ca0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
5cb0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
5cc0: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 hat.** after reb
5cd0: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 oot following a
5ce0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c crash or power l
5cf0: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 oss, the only by
5d00: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 tes in a.** file
5d10: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 that were writt
5d20: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 en at the applic
5d30: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 ation level migh
5d40: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a t have changed.*
5d50: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 * and that adjac
5d60: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 ent bytes, even
5d70: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 bytes within the
5d80: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 same sector are
5d90: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 .** guaranteed t
5da0: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a o be unchanged..
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5dc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
5dd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
5de0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
5df0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
5e00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 TOMIC512
5e10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
5e20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5e30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
5e40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
5e50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
5e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5e70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 MIC2K
5e80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
5e90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5ea0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 CAP_ATOMIC4K
5eb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
5ec0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
5ed0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5ee0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C8K
5ef0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
5f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5f10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
5f20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5f30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 040.#define SQLI
5f40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
5f50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
5f60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
5f70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5f80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
5fa0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5fb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
5fc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 ND 0x
5fd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
5fe0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
5ff0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 QUENTIAL
6000: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6020: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
6030: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 _WHEN_OPEN 0x00
6040: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
6050: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
6060: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
6070: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 0x00001000../
6080: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
6090: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
60a0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 ls.**.** SQLite
60b0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
60c0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
60d0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
60e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
60f0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
6100: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
6110: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
6120: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
6130: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
6140: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
6150: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
6160: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
6170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6180: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
6190: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
61a0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
61b0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
61c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
61d0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
61e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
61f0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
6200: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6210: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
6220: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a Type Flags.**.**
6230: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
6240: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 okes the xSync()
6250: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a method of an.**
6260: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6270: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 hods] object it
6280: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 uses a combinati
6290: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 on of.** these i
62a0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
62b0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
62c0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
62d0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
62e0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 _DATAONLY flag i
62f0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 s used, it means
6300: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e that the.** syn
6310: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 c operation only
6320: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 needs to flush
6330: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f data to mass sto
6340: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 rage. Inode.**
6350: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 information need
6360: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e not be flushed.
6370: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
6380: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 ur bits of the f
6390: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c lag.** equal SQL
63a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c ITE_SYNC_NORMAL,
63b0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 that means to u
63c0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
63d0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 ) semantics..**
63e0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
63f0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c r bits equal SQL
6400: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 ITE_SYNC_FULL, t
6410: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 hat means.** to
6420: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 use Mac OS X sty
6430: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
6440: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
6450: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e **.** Do not con
6460: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f fuse the SQLITE_
6470: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
6480: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
6490: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 flags.** with t
64a0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 he [PRAGMA synch
64b0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 ronous]=NORMAL a
64c0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 nd [PRAGMA synch
64d0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 ronous]=FULL.**
64e0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b settings. The [
64f0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 synchronous prag
6500: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 ma] determines w
6510: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 hen calls to the
6520: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 .** xSync VFS me
6530: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 thod occur and a
6540: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 pplies uniformly
6550: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 across all plat
6560: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 forms..** The SQ
6570: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
6580: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
6590: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 _FULL flags dete
65a0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 rmine how.** ene
65b0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f rgetic or rigoro
65c0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 us or forceful t
65d0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f he sync operatio
65e0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e ns are and.** on
65f0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 ly make a differ
6600: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 ence on Mac OSX
6610: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 for the default
6620: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 SQLite code..**
6630: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 (Third-party VFS
6640: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
6650: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 might also make
6660: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
6670: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
6680: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
6690: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
66a0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 ULL, but among t
66b0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 he.** operating
66c0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 systems natively
66d0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
66e0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f Lite, only Mac O
66f0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 SX.** cares abou
6700: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 t the difference
6710: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 .).*/.#define SQ
6720: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
6730: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
6740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
6750: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
6760: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
6770: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
6780: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
6790: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
67a0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
67b0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
67c0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
67d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
67e0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
67f0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
6800: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
6810: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
6820: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
6830: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
6840: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
6850: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
6860: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
6870: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
6880: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
6890: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
68a0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
68b0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
68c0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
68d0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
68e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
68f0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
6900: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
6910: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
6920: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
6930: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
6940: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
6950: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
6960: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
6970: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
6980: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
6990: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
69a0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
69b0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
69c0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
69d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
69e0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
69f0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
6a00: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
6a10: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
6a20: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
6a30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
6a40: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
6a50: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
6a60: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
6a70: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
6a80: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
6a90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
6aa0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
6ab0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
6ac0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
6ad0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
6ae0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
6af0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
6b00: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
6b10: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
6b20: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
6b30: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
6b40: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
6b50: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
6b60: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 .**.** If the [s
6b70: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
6b80: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 ] method sets th
6b90: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
6ba0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
6bb0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
6bc0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
6bd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
6be0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
6bf0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
6c00: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
6c10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
6c20: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 xOpen] reported
6c30: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
6c40: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
6c50: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
6c60: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
6c70: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
6c80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
6c90: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 en].** is for th
6ca0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
6cb0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 Open] to set the
6cc0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
6cd0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a ethods element.*
6ce0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a * to NULL..**.**
6cf0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
6d00: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 ent to xSync may
6d10: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 be one of [SQLI
6d20: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 TE_SYNC_NORMAL]
6d30: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 or.** [SQLITE_SY
6d40: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 NC_FULL]. The f
6d50: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 irst choice is t
6d60: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 he normal fsync(
6d70: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
6d80: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 choice is a Mac
6d90: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
6da0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 sync. The [SQLI
6db0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
6dc0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 ].** flag may be
6dd0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 ORed in to indi
6de0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 cate that only t
6df0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 he data of the f
6e00: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 ile.** and not i
6e10: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 ts inode needs t
6e20: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a o be synced..**.
6e30: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
6e40: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
6e50: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
6e60: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c re one of.** <ul
6e70: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
6e80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a E_LOCK_NONE],.**
6e90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
6ea0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c CK_SHARED],.** <
6eb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
6ec0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c _RESERVED],.** <
6ed0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
6ee0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a _PENDING], or.**
6ef0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
6f00: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a CK_EXCLUSIVE]..*
6f10: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b * </ul>.** xLock
6f20: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 () increases the
6f30: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 lock. xUnlock()
6f40: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c decreases the l
6f50: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 ock..** The xChe
6f60: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
6f70: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 method checks w
6f80: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 hether any datab
6f90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a ase connection,.
6fa0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 ** either in thi
6fb0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 s process or in
6fc0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 some other proce
6fd0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ss, is holding a
6fe0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 RESERVED,.** PE
6ff0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 NDING, or EXCLUS
7000: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 IVE lock on the
7010: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e file. It return
7020: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 s true.** if suc
7030: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 h a lock exists
7040: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 and false otherw
7050: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ise..**.** The x
7060: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 FileControl() me
7070: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 thod is a generi
7080: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 c interface that
7090: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a allows custom.*
70a0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 * VFS implementa
70b0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c tions to directl
70c0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 y control an ope
70d0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 n file using the
70e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
70f0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
7100: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 erface. The sec
7110: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e ond "op" argumen
7120: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 t is an.** integ
7130: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 er opcode. The
7140: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
7150: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
7160: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a ter intended to.
7170: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 ** point to a st
7180: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
7190: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
71a0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
71b0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
71c0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
71d0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
71e0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
71f0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
7200: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
7210: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
7220: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
7230: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
7240: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
7250: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
7260: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
7270: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
7280: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
7290: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
72a0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
72b0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
72c0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
72d0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f eserves all opco
72e0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 des less than 10
72f0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 0 for its own us
7300: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f e..** A [SQLITE_
7310: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
7320: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 | list of opcode
7330: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 s] less than 100
7340: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a is available..*
7350: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * Applications t
7360: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 hat define a cus
7370: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c tom xFileControl
7380: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 method should u
7390: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 se opcodes.** gr
73a0: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 eater than 100 t
73b0: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 o avoid conflict
73c0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e s. VFS implemen
73d0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a tations should.*
73e0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
73f0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 _NOTFOUND] for f
7400: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
7410: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f des that they do
7420: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a not.** recogniz
7430: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 e..**.** The xSe
7440: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f ctorSize() metho
7450: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 d returns the se
7460: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 ctor size of the
7470: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 .** device that
7480: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 underlies the fi
7490: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 le. The sector
74a0: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d size is the.** m
74b0: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 inimum write tha
74c0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d t can be perform
74d0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 ed without distu
74e0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 rbing.** other b
74f0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 ytes in the file
7500: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 . The xDeviceCh
7510: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a aracteristics().
7520: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e ** method return
7530: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 s a bit vector d
7540: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 escribing behavi
7550: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e ors of the.** un
7560: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a derlying device:
7570: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
7580: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
7590: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 P_ATOMIC].** <li
75a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
75b0: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c ATOMIC512].** <l
75c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
75d0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC1K].** <l
75e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
75f0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC2K].** <l
7600: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
7610: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC4K].** <l
7620: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
7630: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC8K].** <l
7640: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
7650: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c _ATOMIC16K].** <
7660: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
7670: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 P_ATOMIC32K].**
7680: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7690: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a AP_ATOMIC64K].**
76a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
76b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d CAP_SAFE_APPEND]
76c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
76d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
76e0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a L].** </ul>.**.*
76f0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 * The SQLITE_IOC
7700: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 AP_ATOMIC proper
7710: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c ty means that al
7720: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 l writes of.** a
7730: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d ny size are atom
7740: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
7750: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 IOCAP_ATOMICnnn
7760: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 values.** mean t
7770: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c hat writes of bl
7780: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e ocks that are nn
7790: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 n bytes in size
77a0: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e and.** are align
77b0: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 ed to an address
77c0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 which is an int
77d0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 eger multiple of
77e0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d .** nnn are atom
77f0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
7800: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
7810: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a D value means.**
7820: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 that when data
7830: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 is appended to a
7840: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 file, the data
7850: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 is appended.** f
7860: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 irst then the si
7870: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 ze of the file i
7880: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 s extended, neve
7890: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 r the other.** w
78a0: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 ay around. The
78b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
78c0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 UENTIAL property
78d0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 means that.** i
78e0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 nformation is wr
78f0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e itten to disk in
7900: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 the same order
7910: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 as calls.** to x
7920: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 Write()..**.** I
7930: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e f xRead() return
7940: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 s SQLITE_IOERR_S
7950: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 HORT_READ it mus
7960: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 t also fill.** i
7970: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 n the unread por
7980: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 tions of the buf
7990: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 fer with zeros.
79a0: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 A VFS that.** f
79b0: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c ails to zero-fil
79c0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 l short reads mi
79d0: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b ght seem to work
79e0: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
79f0: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 ailure to zero-f
7a00: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 ill short reads
7a10: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 will eventually
7a20: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 lead to.** datab
7a30: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a ase corruption..
7a40: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
7a50: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
7a60: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f hods sqlite3_io_
7a70: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
7a80: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7a90: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 ds {. int iVers
7aa0: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c ion;. int (*xCl
7ab0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ose)(sqlite3_fil
7ac0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 e*);. int (*xRe
7ad0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ad)(sqlite3_file
7ae0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 *, void*, int iA
7af0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 mt, sqlite3_int6
7b00: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 4 iOfst);. int
7b10: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 (*xWrite)(sqlite
7b20: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 3_file*, const v
7b30: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
7b40: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
7b50: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 fst);. int (*xT
7b60: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 runcate)(sqlite3
7b70: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
7b80: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 int64 size);. i
7b90: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 nt (*xSync)(sqli
7ba0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 te3_file*, int f
7bb0: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 lags);. int (*x
7bc0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 FileSize)(sqlite
7bd0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
7be0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a _int64 *pSize);.
7bf0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 int (*xLock)(s
7c00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
7c10: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c t);. int (*xUnl
7c20: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
7c30: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
7c40: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 (*xCheckReserved
7c50: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
7c60: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 le*, int *pResOu
7c70: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c t);. int (*xFil
7c80: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 eControl)(sqlite
7c90: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 3_file*, int op,
7ca0: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 void *pArg);.
7cb0: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a int (*xSectorSiz
7cc0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
7cd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 );. int (*xDevi
7ce0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
7cf0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a s)(sqlite3_file*
7d00: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 );. /* Methods
7d10: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 above are valid
7d20: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f for version 1 */
7d30: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 . int (*xShmMap
7d40: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7d50: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 int iPg, int pg
7d60: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f sz, int, void vo
7d70: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 latile**);. int
7d80: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c (*xShmLock)(sql
7d90: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
7da0: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 offset, int n, i
7db0: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 nt flags);. voi
7dc0: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 d (*xShmBarrier)
7dd0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
7de0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d . int (*xShmUnm
7df0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ap)(sqlite3_file
7e00: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 *, int deleteFla
7e10: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 g);. /* Methods
7e20: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 above are valid
7e30: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a for version 2 *
7e40: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 /. /* Additiona
7e50: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 l methods may be
7e60: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
7e70: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a releases */.};.
7e80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
7e90: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 Standard File C
7ea0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a ontrol Opcodes.*
7eb0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
7ec0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
7ed0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
7ee0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
7ef0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
7f00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7f10: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
7f20: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
7f30: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
7f40: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
7f50: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
7f60: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
7f70: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
7f80: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 for debugging.
7f90: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 This.** opcode c
7fa0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 auses the xFileC
7fb0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f ontrol method to
7fc0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 write the curre
7fd0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 nt state of.** t
7fe0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 he lock (one of
7ff0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e [SQLITE_LOCK_NON
8000: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b E], [SQLITE_LOCK
8010: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 _SHARED],.** [SQ
8020: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
8030: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 ED], [SQLITE_LOC
8040: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b K_PENDING], or [
8050: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
8060: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 USIVE]).** into
8070: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 an integer that
8080: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e the pArg argumen
8090: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 t points to. Thi
80a0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 s capability.**
80b0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 is used during t
80c0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 esting and only
80d0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 needs to be supp
80e0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 orted when SQLIT
80f0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 E_TEST.** is def
8100: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ined..**.** The
8110: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
8120: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 ZE_HINT] opcode
8130: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 is used by SQLit
8140: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 e to give the VF
8150: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e S.** layer a hin
8160: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 t of how large t
8170: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
8180: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 will grow to be
8190: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 during the.** c
81a0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 urrent transacti
81b0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 on. This hint i
81c0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
81d0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 to be accurate
81e0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 but it.** is oft
81f0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 en close. The u
8200: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 nderlying VFS mi
8210: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 ght choose to pr
8220: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 eallocate databa
8230: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 se.** file space
8240: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 based on this h
8250: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 int in order to
8260: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 help writes to t
8270: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 he database.** f
8280: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a ile run faster..
8290: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
82a0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
82b0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ZE] opcode is us
82c0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 ed to request th
82d0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 at the VFS.** ex
82e0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 tends and trunca
82f0: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 tes the database
8300: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 file in chunks
8310: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 of a size specif
8320: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 ied.** by the us
8330: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 er. The fourth a
8340: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
8350: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
8360: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 ()] should .** p
8370: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 oint to an integ
8380: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f er (type int) co
8390: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 ntaining the new
83a0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 chunk-size to u
83b0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f se.** for the no
83c0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 minated database
83d0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 . Allocating dat
83e0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 abase file space
83f0: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 in large.** chu
8400: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 nks (say 1MB at
8410: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 a time), may red
8420: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 uce file-system
8430: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e fragmentation an
8440: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 d.** improve per
8450: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 formance on some
8460: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 systems..**.**
8470: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
8480: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 L_FILE_POINTER]
8490: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
84a0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
84b0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
84c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
84d0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
84e0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
84f0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
8500: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 ection. See the
8510: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
8520: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 ontrol()] docume
8530: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 ntation for.** a
8540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
8550: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ation..**.** ^(T
8560: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
8570: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f _SYNC_OMITTED] o
8580: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
8590: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
85a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 .** SQLite and s
85b0: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 ent to all VFSes
85c0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 in place of a c
85d0: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 all to the xSync
85e0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 method.** when
85f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
8600: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 nection has [PRA
8610: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d GMA synchronous]
8620: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a set to OFF.)^.*
8630: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a * Some specializ
8640: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 ed VFSes need th
8650: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 is signal in ord
8660: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f er to operate co
8670: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 rrectly.** when
8680: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
8690: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e ous | PRAGMA syn
86a0: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 chronous=OFF] is
86b0: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a set, but most .
86c0: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 ** VFSes do not
86d0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c need this signal
86e0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 and should sile
86f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
8700: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c opcode..** Appl
8710: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
8720: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 not call [sqlite
8730: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
8740: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f ] with this.** o
8750: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 pcode as doing s
8760: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 o may disrupt th
8770: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 e operation of t
8780: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 he specialized V
8790: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 FSes.** that do
87a0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a require it. .**
87b0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
87c0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
87d0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 RETRY] opcode is
87e0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
87f0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 re automatic.**
8800: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 retry counts and
8810: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 intervals for c
8820: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 ertain disk I/O
8830: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 operations for t
8840: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 he.** windows [V
8850: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 FS] in order to
8860: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 provide robustne
8870: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e ss in the presen
8880: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 ce of.** anti-vi
8890: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 rus programs. B
88a0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 y default, the w
88b0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 indows VFS will
88c0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c retry file read,
88d0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 .** file write,
88e0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 and file delete
88f0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f operations up to
8900: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 10 times, with
8910: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 a delay.** of 25
8920: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 milliseconds be
8930: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 fore the first r
8940: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 etry and with th
8950: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 e delay increasi
8960: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 ng.** by an addi
8970: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 tional 25 millis
8980: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 econds with each
8990: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 subsequent retr
89a0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f y. This.** opco
89b0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 de allows these
89c0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 two values (10 r
89d0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 etries and 25 mi
89e0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 lliseconds of de
89f0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 lay).** to be ad
8a00: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c justed. The val
8a10: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 ues are changed
8a20: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 for all database
8a30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
8a40: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
8a50: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 process. The ar
8a60: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
8a70: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 ter to an array
8a80: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 of two.** intege
8a90: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 rs where the fir
8aa0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 st integer i the
8ab0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 new retry count
8ac0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a and the second.
8ad0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 ** integer is th
8ae0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 e delay. If eit
8af0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e her integer is n
8b00: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
8b10: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 e setting.** is
8b20: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 not changed but
8b30: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f instead the prio
8b40: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 r value of that
8b50: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 setting is writt
8b60: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 en.** into the a
8b70: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f rray entry, allo
8b80: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 wing the current
8b90: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 retry settings
8ba0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f to be.** interro
8bb0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e gated. The zDbN
8bc0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
8bd0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
8be0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
8bf0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 TL_PERSIST_WAL]
8c00: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
8c10: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 o set or query t
8c20: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 he.** persistent
8c30: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 48 [WAL | Write AH
8c40: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 ead Log] setting
8c50: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 . By default, t
8c60: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 he auxiliary.**
8c70: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 write ahead log
8c80: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 and shared memor
8c90: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 y files used for
8ca0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e transaction con
8cb0: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f trol.** are auto
8cc0: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 matically delete
8cd0: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 d when the lates
8ce0: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 t connection to
8cf0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
8d00: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 closes. Setting
8d10: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 persistent WAL
8d20: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 mode causes thos
8d30: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 e files to persi
8d40: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 st after.** clos
8d50: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 e. Persisting t
8d60: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 he files is usef
8d70: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 ul when other pr
8d80: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 ocesses that do
8d90: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 not.** have writ
8da0: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 e permission on
8db0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f the directory co
8dc0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 ntaining the dat
8dd0: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a abase file want.
8de0: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 ** to read the d
8df0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 atabase file, as
8e00: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 the WAL and sha
8e10: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
8e20: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 must exist.** i
8e30: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 n order for the
8e40: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 database to be r
8e50: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f eadable. The fo
8e60: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
8e70: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 o.** [sqlite3_fi
8e80: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f le_control()] fo
8e90: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 r this opcode sh
8ea0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 ould be a pointe
8eb0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e r to an integer.
8ec0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 .** That integer
8ed0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
8ee0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 persistent WAL
8ef0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 mode or 1 to ena
8f00: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a ble persistent.*
8f10: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 * WAL mode. If
8f20: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d the integer is -
8f30: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 1, then it is ov
8f40: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
8f50: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 he current.** WA
8f60: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 L persistence se
8f70: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tting..**.** ^Th
8f80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
8f90: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
8fa0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ITE] opcode is u
8fb0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
8fc0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
8fd0: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 stent "powersafe
8fe0: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 -overwrite" or "
8ff0: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 PSOW" setting.
9000: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 The PSOW setting
9010: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 .** determines t
9020: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 he [SQLITE_IOCAP
9030: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
9040: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 RITE] bit of the
9050: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 .** xDeviceChara
9060: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
9070: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 ds. The fourth p
9080: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
9090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
90a0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 trol()] for this
90b0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 opcode should b
90c0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
90d0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 n integer..** Th
90e0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 at integer is 0
90f0: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d to disable zero-
9100: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 damage mode or 1
9110: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d to enable zero-
9120: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 damage.** mode.
9130: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
9140: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
9150: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
9160: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
9170: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f * zero-damage mo
9180: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a de setting..**.*
9190: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
91a0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 CNTL_OVERWRITE]
91b0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 opcode is invoke
91c0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 d by SQLite afte
91d0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 r opening.** a w
91e0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
91f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
9200: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 t, unless it is
9210: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 rolled back for
9220: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 some.** reason,
9230: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 the entire datab
9240: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 ase file will be
9250: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
9260: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
9270: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
9280: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 s is used by VAC
9290: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a UUM operations..
92a0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 **.** ^The [SQLI
92b0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
92c0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 ] opcode can be
92d0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 used to obtain t
92e0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 he names of.** a
92f0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 ll [VFSes] in th
9300: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 e VFS stack. Th
9310: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 e names are of a
9320: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 ll VFS shims and
9330: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f the.** final bo
9340: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 ttom-level VFS a
9350: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 re written into
9360: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
9370: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
9380: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
9390: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 the result is st
93a0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 ored in the char
93b0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 * variable.** th
93c0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 at the fourth pa
93d0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 rameter of [sqli
93e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
93f0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a ()] points to..*
9400: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 * The caller is
9410: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
9420: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f freeing the memo
9430: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 ry when done. A
9440: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 s with.** all fi
9450: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f le-control actio
9460: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 ns, there is no
9470: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
9480: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c his will actuall
9490: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 y.** do anything
94a0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c . Callers shoul
94b0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 d initialize the
94c0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 char* variable
94d0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 to a NULL.** poi
94e0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 nter in case thi
94f0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
9500: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 s not implemente
9510: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f d. This file-co
9520: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 ntrol.** is inte
9530: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 nded for diagnos
9540: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2f tic use only..*/
9550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9560: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
9570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 1.
9580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
9590: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
95a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
95b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
95c0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
95d0: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
95e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 efine SQLITE_LAS
95f0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 T_ERRNO
9600: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
9610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
9620: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 L_SIZE_HINT
9630: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
9640: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
9650: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 _CHUNK_SIZE
9660: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
9670: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
9680: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 FILE_POINTER
9690: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
96a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
96b0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 YNC_OMITTED
96c0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
96d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
96e0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 N32_AV_RETRY
96f0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
9700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
9710: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 SIST_WAL
9720: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
9730: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
9740: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
9750: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 11.#define SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
9770: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ME
9780: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 12.#define SQL
9790: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
97a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 AFE_OVERWRITE
97b0: 20 31 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 13../*.** CAPI3
97c0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c REF: Mutex Handl
97d0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 e.**.** The mute
97e0: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 x module within
97f0: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b SQLite defines [
9800: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 sqlite3_mutex] t
9810: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 o be an.** abstr
9820: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d act type for a m
9830: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 utex object. Th
9840: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 e SQLite core ne
9850: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 ver looks.** at
9860: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
9870: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 resentation of a
9880: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 n [sqlite3_mutex
9890: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 ]. It only.** d
98a0: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 eals with pointe
98b0: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 rs to the [sqlit
98c0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 e3_mutex] object
98d0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 ..**.** Mutexes
98e0: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e are created usin
98f0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
9900: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 _alloc()]..*/.ty
9910: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
9920: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 ite3_mutex sqlit
9930: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a e3_mutex;../*.**
9940: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
9950: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a terface Object.*
9960: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
9970: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
9980: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e vfs object defin
9990: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
99a0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
99b0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 SQLite core and
99c0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f the underlying o
99d0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
99e0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 The "vfs".** i
99f0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
9a00: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 e object stands
9a10: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c for "virtual fil
9a20: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a e system". See.
9a30: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 ** the [VFS | VF
9a40: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d S documentation]
9a50: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 for further inf
9a60: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
9a70: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 The value of the
9a80: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
9a90: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 is initially 1 b
9aa0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 ut may be larger
9ab0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 in.** future ve
9ac0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
9ad0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 . Additional fi
9ae0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 elds may be appe
9af0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 nded to this.**
9b00: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 object when the
9b10: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 iVersion value i
9b20: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f s increased. No
9b30: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 te that the stru
9b40: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 cture.** of the
9b50: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
9b60: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ct changes in th
9b70: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 e transaction be
9b80: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 tween.** SQLite
9b90: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e version 3.5.9 an
9ba0: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 d 3.6.0 and yet
9bb0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
9bc0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f ld was not.** mo
9bd0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 dified..**.** Th
9be0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 e szOsFile field
9bf0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
9c00: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b the subclassed [
9c10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a sqlite3_file].**
9c20: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 structure used
9c30: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 by this VFS. mx
9c40: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 Pathname is the
9c50: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
9c60: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 f.** a pathname
9c70: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a in this VFS..**.
9c80: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 ** Registered sq
9c90: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
9ca0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 s are kept on a
9cb0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d linked list form
9cc0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 ed by.** the pNe
9cd0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 xt pointer. The
9ce0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 [sqlite3_vfs_re
9cf0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 gister()].** and
9d00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e [sqlite3_vfs_un
9d10: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 register()] inte
9d20: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 rfaces manage th
9d30: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 is list.** in a
9d40: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e thread-safe way.
9d50: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
9d60: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 fs_find()] inter
9d70: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 face.** searches
9d80: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 the list. Neit
9d90: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 her the applicat
9da0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 ion code nor the
9db0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e VFS.** implemen
9dc0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 tation should us
9dd0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e e the pNext poin
9de0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 ter..**.** The p
9df0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 Next field is th
9e00: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 e only field in
9e10: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
9e20: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 ** structure tha
9e30: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 t SQLite will ev
9e40: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 er modify. SQLi
9e50: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 te will only acc
9e60: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 ess.** or modify
9e70: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c this field whil
9e80: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 e holding a part
9e90: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 icular static mu
9ea0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c tex..** The appl
9eb0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e ication should n
9ec0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 ever modify anyt
9ed0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 hing within the
9ee0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f sqlite3_vfs.** o
9ef0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f bject once the o
9f00: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 bject has been r
9f10: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a egistered..**.**
9f20: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 The zName field
9f30: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 holds the name
9f40: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c of the VFS modul
9f50: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 e. The name mus
9f60: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 t.** be unique a
9f70: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f cross all VFS mo
9f80: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 dules..**.** [[s
9f90: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
9fa0: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 ]].** ^SQLite gu
9fb0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 arantees that th
9fc0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
9fd0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a meter to xOpen.*
9fe0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 * is either a NU
9ff0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 LL pointer or st
a000: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a ring obtained.**
a010: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e from xFullPathn
a020: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 ame() with an op
a030: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 tional suffix ad
a040: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 ded..** ^If a su
a050: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f ffix is added to
a060: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
a070: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c arameter, it wil
a080: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 l.** consist of
a090: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 a single "-" cha
a0a0: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 racter followed
a0b0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a by no more than.
a0c0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 ** 11 alphanumer
a0d0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 ic and/or "-" ch
a0e0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 aracters..** ^SQ
a0f0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 Lite further gua
a100: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 rantees that.**
a110: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 the string will
a120: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 be valid and unc
a130: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c hanged until xCl
a140: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c ose() is.** call
a150: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 ed. Because of t
a160: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
a170: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 ence,.** the [sq
a180: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 lite3_file] can
a190: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 safely store a p
a1a0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
a1b0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 filename if it
a1c0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 needs to remembe
a1d0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 r the filename f
a1e0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a or some reason..
a1f0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e ** If the zFilen
a200: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f ame parameter to
a210: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c xOpen is a NULL
a220: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f pointer then xO
a230: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 pen.** must inve
a240: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f nt its own tempo
a250: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 rary name for th
a260: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 e file. ^Whenev
a270: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 er the .** xFile
a280: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 name parameter i
a290: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 s NULL it will a
a2a0: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 lso be the case
a2b0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 that the.** flag
a2c0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c s parameter will
a2d0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
a2e0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
a2f0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 OSE]..**.** The
a300: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
a310: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 o xOpen() includ
a320: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 es all bits set
a330: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 in.** the flags
a340: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c argument to [sql
a350: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e ite3_open_v2()].
a360: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 Or if [sqlite3
a370: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b _open()].** or [
a380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
a390: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 ] is used, then
a3a0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 flags includes a
a3b0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 t least.** [SQLI
a3c0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
a3d0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 E] | [SQLITE_OPE
a3e0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 N_CREATE]. .** I
a3f0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 f xOpen() opens
a400: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 a file read-only
a410: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 then it sets *p
a420: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 OutFlags to.** i
a430: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f nclude [SQLITE_O
a440: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 PEN_READONLY].
a450: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 Other bits in *p
a460: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 OutFlags may be
a470: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c set..**.** ^(SQL
a480: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 ite will also ad
a490: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
a4a0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
a4b0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 the xOpen().** c
a4c0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f all, depending o
a4d0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 n the object bei
a4e0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a ng opened:.**.**
a4f0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b <ul>.** <li> [
a500: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
a510: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
a520: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
a530: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
a540: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
a550: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 EMP_DB].** <li>
a560: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 [SQLITE_OPEN_TE
a570: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c MP_JOURNAL].** <
a580: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
a590: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a N_TRANSIENT_DB].
a5a0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
a5b0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c _OPEN_SUBJOURNAL
a5c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
a5d0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a TE_OPEN_MASTER_J
a5e0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
a5f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 [SQLITE_OPEN_WA
a600: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a L].** </ul>)^.**
a610: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f .** The file I/O
a620: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
a630: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 can use the obje
a640: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f ct type flags to
a650: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 .** change the w
a660: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 ay it deals with
a670: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 files. For exa
a680: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 mple, an applica
a690: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 tion.** that doe
a6a0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 s not care about
a6b0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 crash recovery
a6c0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 or rollback migh
a6d0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 t make.** the op
a6e0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 en of a journal
a6f0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 file a no-op. W
a700: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f rites to this jo
a710: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 urnal would.** a
a720: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 lso be no-ops, a
a730: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 nd any attempt t
a740: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e o read the journ
a750: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a al would return.
a760: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e ** SQLITE_IOERR.
a770: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 Or the impleme
a780: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ntation might re
a790: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 cognize that a d
a7a0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
a7b0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 will be doing pa
a7c0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f ge-aligned secto
a7d0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 r reads and writ
a7e0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a es in a random.*
a7f0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 * order and set
a800: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 up its I/O subsy
a810: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 stem accordingly
a820: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d ..**.** SQLite m
a830: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e ight also add on
a840: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
a850: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
a860: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a xOpen method:.**
a870: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
a880: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
a890: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
a8a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
a8b0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 N_EXCLUSIVE].**
a8c0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
a8d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
a8e0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 ETEONCLOSE] flag
a8f0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 means the file
a900: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c should be.** del
a910: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 eted when it is
a920: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 closed. ^The [S
a930: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
a940: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c EONCLOSE].** wil
a950: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d l be set for TEM
a960: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 P databases and
a970: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 their journals,
a980: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 transient.** dat
a990: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a abases, and subj
a9a0: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e ournals..**.** ^
a9b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
a9c0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 _EXCLUSIVE] flag
a9d0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 is always used
a9e0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a in conjunction.*
a9f0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 * with the [SQLI
aa00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 TE_OPEN_CREATE]
aa10: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 flag, which are
aa20: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a both directly.**
aa30: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 analogous to th
aa40: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 e O_EXCL and O_C
aa50: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 REAT flags of th
aa60: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a e POSIX open().*
aa70: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 * API. The SQLI
aa80: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
aa90: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 E flag, when pai
aaa0: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a red with the .**
aab0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
aac0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 ATE, is used to
aad0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 indicate that fi
aae0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 le should always
aaf0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 .** be created,
ab00: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 and that it is a
ab10: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c n error if it al
ab20: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a ready exists..**
ab30: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 It is <i>not</i
ab40: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 > used to indica
ab50: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 te the file shou
ab60: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a ld be opened .**
ab70: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 for exclusive a
ab80: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 ccess..**.** ^At
ab90: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 least szOsFile
aba0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 bytes of memory
abb0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 are allocated by
abc0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f SQLite.** to ho
abd0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 ld the [sqlite3
abe0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 _file] structure
abf0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
ac00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 hird.** argument
ac10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 to xOpen. The
ac20: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 xOpen method doe
ac30: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a s not have to.**
ac40: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 allocate the st
ac50: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 ructure; it shou
ac60: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 ld just fill it
ac70: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a in. Note that.*
ac80: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 * the xOpen meth
ac90: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 od must set the
aca0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
acb0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a thods to either.
acc0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 ** a valid [sqli
acd0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
ace0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c object or to NUL
acf0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 L. xOpen must d
ad00: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 o.** this even i
ad10: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 f the open fails
ad20: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 . SQLite expect
ad30: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 s that the sqlit
ad40: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
ad50: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c .** element will
ad60: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 be valid after
ad70: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 xOpen returns re
ad80: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
ad90: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 success.** or fa
ada0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 ilure of the xOp
adb0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b en call..**.** [
adc0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 [sqlite3_vfs.xAc
add0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 cess]].** ^The f
ade0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
adf0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 xAccess() may b
ae00: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 e [SQLITE_ACCESS
ae10: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 _EXISTS].** to t
ae20: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 est for the exis
ae30: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c tence of a file,
ae40: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 or [SQLITE_ACCE
ae50: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f SS_READWRITE] to
ae60: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 .** test whether
ae70: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 a file is reada
ae80: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 ble and writable
ae90: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 , or [SQLITE_ACC
aea0: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 ESS_READ].** to
aeb0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
aec0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 ile is at least
aed0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 readable. The
aee0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a file can be a.**
aef0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a directory..**.*
af00: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 * ^SQLite will a
af10: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 lways allocate a
af20: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 t least mxPathna
af30: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 me+1 bytes for t
af40: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 he.** output buf
af50: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d fer xFullPathnam
af60: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 e. The exact si
af70: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 ze of the output
af80: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c buffer.** is al
af90: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 so passed as a p
afa0: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 arameter to both
afb0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 methods. If th
afc0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a e output buffer.
afd0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 ** is not large
afe0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f enough, [SQLITE_
aff0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 CANTOPEN] should
b000: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 be returned. Si
b010: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 nce this is.** h
b020: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 andled as a fata
b030: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 l error by SQLit
b040: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 e, vfs implement
b050: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e ations should en
b060: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 deavor.** to pre
b070: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 vent this by set
b080: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 ting mxPathname
b090: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c to a sufficientl
b0a0: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a y large value..*
b0b0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d *.** The xRandom
b0c0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 ness(), xSleep()
b0d0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 , xCurrentTime()
b0e0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 , and xCurrentTi
b0f0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 meInt64().** int
b100: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 erfaces are not
b110: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 strictly a part
b120: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 of the filesyste
b130: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a m, but they are.
b140: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 ** included in t
b150: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 he VFS structure
b160: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 for completenes
b170: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f s..** The xRando
b180: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e mness() function
b190: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 attempts to ret
b1a0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 urn nBytes bytes
b1b0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c .** of good-qual
b1c0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 ity randomness i
b1d0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 nto zOut. The r
b1e0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a eturn value is.*
b1f0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d * the actual num
b200: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 ber of bytes of
b210: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 randomness obtai
b220: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 ned..** The xSle
b230: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 ep() method caus
b240: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 es the calling t
b250: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 hread to sleep f
b260: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 or at.** least t
b270: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 he number of mic
b280: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e roseconds given.
b290: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 ^The xCurrentT
b2a0: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ime().** method
b2b0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e returns a Julian
b2c0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 Day Number for
b2d0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 the current date
b2e0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 and time as.**
b2f0: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 a floating point
b300: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 value..** ^The
b310: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
b320: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 4() method retur
b330: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 ns, as an intege
b340: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a r, the Julian.**
b350: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 Day Number mult
b360: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 iplied by 864000
b370: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 00 (the number o
b380: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 f milliseconds i
b390: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 n .** a 24-hour
b3a0: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 day). .** ^SQLi
b3b0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 te will use the
b3c0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
b3d0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 4() method to ge
b3e0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a t the current.**
b3f0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 date and time i
b400: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 f that method is
b410: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 available (if i
b420: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 Version is 2 or
b430: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 .** greater and
b440: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 the function poi
b450: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
b460: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 ) and will fall
b470: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 back.** to xCurr
b480: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 entTime() if xCu
b490: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
b4a0: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e is unavailable.
b4b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 .**.** ^The xSet
b4c0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 SystemCall(), xG
b4d0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 etSystemCall(),
b4e0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 and xNestSystemC
b4f0: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 all() interfaces
b500: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 .** are not used
b510: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 by the SQLite c
b520: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 ore. These opti
b530: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 onal interfaces
b540: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 are provided.**
b550: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f by some VFSes to
b560: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 facilitate test
b570: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 ing of the VFS c
b580: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 ode. By overridi
b590: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 ng .** system ca
b5a0: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f lls with functio
b5b0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e ns under its con
b5c0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f trol, a test pro
b5d0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 gram can.** simu
b5e0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 late faults and
b5f0: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 error conditions
b600: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 that would othe
b610: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 rwise be difficu
b620: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 lt.** or impossi
b630: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 ble to induce.
b640: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 The set of syste
b650: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e m calls that can
b660: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a be overridden.*
b670: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e * varies from on
b680: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 e VFS to another
b690: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 , and from one v
b6a0: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 ersion of the sa
b6b0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a me VFS to the.**
b6c0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
b6d0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 ions that use th
b6e0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d ese interfaces m
b6f0: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 ust be prepared
b700: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c for any.** or al
b710: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 l of these inter
b720: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c faces to be NULL
b730: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 or for their be
b740: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 havior to change
b750: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c .** from one rel
b760: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 ease to the next
b770: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
b780: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 must not attempt
b790: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e to access.** an
b7a0: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f y of these metho
b7b0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 ds if the iVersi
b7c0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 on of the VFS is
b7d0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f less than 3..*/
b7e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
b7f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 sqlite3_vfs sqli
b800: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 te3_vfs;.typedef
b810: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f void (*sqlite3_
b820: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 syscall_ptr)(voi
b830: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 d);.struct sqlit
b840: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 e3_vfs {. int i
b850: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 Version;
b860: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 /* Structure
b870: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 version number
b880: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f (currently 3) */
b890: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b . int szOsFile;
b8a0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
b8b0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 ize of subclasse
b8c0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a d sqlite3_file *
b8d0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 /. int mxPathna
b8e0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 me; /*
b8f0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 Maximum file pat
b900: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a hname length */.
b910: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 sqlite3_vfs *p
b920: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 Next; /* Ne
b930: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 xt registered VF
b940: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 S */. const cha
b950: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 r *zName;
b960: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 /* Name of this
b970: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
b980: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tem */. void *p
b990: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
b9a0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 /* Pointer to
b9b0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 application-spec
b9c0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 ific data */. i
b9d0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
b9e0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
b9f0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c char *zName, sql
ba00: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 ite3_file*,.
ba10: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 int f
ba20: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 lags, int *pOutF
ba30: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 lags);. int (*x
ba40: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f Delete)(sqlite3_
ba50: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
ba60: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e *zName, int syn
ba70: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 cDir);. int (*x
ba80: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f Access)(sqlite3_
ba90: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
baa0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 *zName, int fla
bab0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 gs, int *pResOut
bac0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c );. int (*xFull
bad0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 Pathname)(sqlite
bae0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
baf0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e ar *zName, int n
bb00: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 Out, char *zOut)
bb10: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f ;. void *(*xDlO
bb20: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 pen)(sqlite3_vfs
bb30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
bb40: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 Filename);. voi
bb50: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 d (*xDlError)(sq
bb60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
bb70: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 nByte, char *zEr
bb80: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a rMsg);. void (*
bb90: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 (*xDlSym)(sqlite
bba0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 3_vfs*,void*, co
bbb0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f nst char *zSymbo
bbc0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 l))(void);. voi
bbd0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 d (*xDlClose)(sq
bbe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 lite3_vfs*, void
bbf0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e *);. int (*xRan
bc00: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 domness)(sqlite3
bc10: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
bc20: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
bc30: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 int (*xSleep)(s
bc40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
bc50: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a microseconds);.
bc60: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 int (*xCurrent
bc70: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 Time)(sqlite3_vf
bc80: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 s*, double*);.
bc90: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 int (*xGetLastEr
bca0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
bcb0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b *, int, char *);
bcc0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d . /*. ** The m
bcd0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
bce0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 in version 1 of
bcf0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
bd00: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 object. ** defi
bd10: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 nition. Those t
bd20: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 hat follow are a
bd30: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 dded in version
bd40: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 2 or later. */.
bd50: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 int (*xCurrent
bd60: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 TimeInt64)(sqlit
bd70: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 e3_vfs*, sqlite3
bd80: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 _int64*);. /*.
bd90: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 ** The methods
bda0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 above are in ver
bdb0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 sions 1 and 2 of
bdc0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
bdd0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f object.. ** Tho
bde0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 se below are for
bdf0: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 version 3 and g
be00: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 reater.. */. i
be10: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 nt (*xSetSystemC
be20: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 all)(sqlite3_vfs
be30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
be40: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 Name, sqlite3_sy
be50: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 scall_ptr);. sq
be60: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 lite3_syscall_pt
be70: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 r (*xGetSystemCa
be80: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ll)(sqlite3_vfs*
be90: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
bea0: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 ame);. const ch
beb0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 ar *(*xNextSyste
bec0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
bed0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
bee0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 *zName);. /*.
bef0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 ** The methods a
bf00: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 bove are in vers
bf10: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 ions 1 through 3
bf20: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
bf30: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 fs object.. **
bf40: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 New fields may b
bf50: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 e appended in fi
bf60: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 gure versions.
bf70: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a The iVersion. *
bf80: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 * value will inc
bf90: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 rement whenever
bfa0: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 this happens. .
bfb0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
bfc0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
bfd0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 r the xAccess VF
bfe0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 S method.**.** T
bff0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
c000: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 stants can be us
c010: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 ed as the third
c020: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
c030: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
c040: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 od of an [sqlite
c050: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 3_vfs] object.
c060: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a They determine.*
c070: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 * what kind of p
c080: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 ermissions the x
c090: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 Access method is
c0a0: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a looking for..**
c0b0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
c0c0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 ESS_EXISTS, the
c0d0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
c0e0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 * simply checks
c0f0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 whether the file
c100: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 exists..** With
c110: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
c120: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 EADWRITE, the xA
c130: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
c140: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
c150: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f he named directo
c160: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 ry is both reada
c170: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 ble and writable
c180: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f .** (in other wo
c190: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 rds, if files ca
c1a0: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f n be added, remo
c1b0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 ved, and renamed
c1c0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 within.** the d
c1d0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 irectory)..** Th
c1e0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
c1f0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 READWRITE consta
c200: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 nt is currently
c210: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 used only by the
c220: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f .** [temp_store_
c230: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 directory pragma
c240: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 ], though this c
c250: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 ould change in a
c260: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 future.** relea
c270: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a se of SQLite..**
c280: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
c290: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 ESS_READ, the xA
c2a0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
c2b0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
c2c0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 he file is reada
c2d0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 ble. The SQLITE
c2e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e _ACCESS_READ con
c2f0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 stant is.** curr
c300: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 ently unused, th
c310: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 ough it might be
c320: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 used in a futur
c330: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 e release of.**
c340: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 SQLite..*/.#defi
c350: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
c360: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 _EXISTS 0.#de
c370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
c380: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 SS_READWRITE 1
c390: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 /* Used by PRAG
c3a0: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 MA temp_store_di
c3b0: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 rectory */.#defi
c3c0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
c3d0: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f _READ 2 /
c3e0: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a * Unused */../*.
c3f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
c400: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c gs for the xShmL
c410: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a ock VFS method.*
c420: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
c430: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 er constants def
c440: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 ine the various
c450: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f locking operatio
c460: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 ns.** allowed by
c470: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 the xShmLock me
c480: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 thod of [sqlite3
c490: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 _io_methods]. T
c4a0: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 he.** following
c4b0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 are the only leg
c4c0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 al combinations
c4d0: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a of flags to the.
c4e0: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 ** xShmLock meth
c4f0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a od:.**.** <ul>.*
c500: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
c510: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 HM_LOCK | SQLITE
c520: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c _SHM_SHARED.** <
c530: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
c540: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
c550: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c M_EXCLUSIVE.** <
c560: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
c570: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f UNLOCK | SQLITE_
c580: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c SHM_SHARED.** <l
c590: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 i> SQLITE_SHM_U
c5a0: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 NLOCK | SQLITE_S
c5b0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 HM_EXCLUSIVE.**
c5c0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e </ul>.**.** When
c5d0: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 unlocking, the
c5e0: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 same SHARED or E
c5f0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 XCLUSIVE flag mu
c600: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 st be supplied a
c610: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e s.** was given n
c620: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 o the correspond
c630: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a ing lock. .**.*
c640: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d * The xShmLock m
c650: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 ethod can transi
c660: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c tion between unl
c670: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 ocked and SHARED
c680: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 or.** between u
c690: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c nlocked and EXCL
c6a0: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f USIVE. It canno
c6b0: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 t transition bet
c6c0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 ween SHARED.** a
c6d0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f nd EXCLUSIVE..*/
c6e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c6f0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 SHM_UNLOCK
c700: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
c710: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 E_SHM_LOCK
c720: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
c730: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 ITE_SHM_SHARED
c740: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
c750: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 QLITE_SHM_EXCLUS
c760: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 IVE 8../*.**
c770: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 CAPI3REF: Maximu
c780: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 m xShmLock index
c790: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c .**.** The xShmL
c7a0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 ock method on [s
c7b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
c7c0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 s] may use value
c7d0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 s.** between 0 a
c7e0: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f nd this upper bo
c7f0: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 und as its "offs
c800: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a et" argument..**
c810: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
c820: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 will never atte
c830: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f mpt to acquire o
c840: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c r release a.** l
c850: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 ock outside of t
c860: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 his range.*/.#de
c870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
c880: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a NLOCK 8..
c890: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
c8a0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 Initialize The
c8b0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a SQLite Library.*
c8c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
c8d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 3_initialize() r
c8e0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a outine initializ
c8f0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 es the.** SQLite
c900: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 library. ^The
c910: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
c920: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 () routine.** de
c930: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 allocates any re
c940: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 sources that wer
c950: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 e allocated by s
c960: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
c970: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f e()..** These ro
c980: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 utines are desig
c990: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 ned to aid in pr
c9a0: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 ocess initializa
c9b0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 tion and.** shut
c9c0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 down on embedded
c9d0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 systems. Works
c9e0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 tation applicati
c9f0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c ons using.** SQL
ca00: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 ite normally do
ca10: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f not need to invo
ca20: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 ke either of the
ca30: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
ca40: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
ca50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
ca60: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
ca70: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
ca80: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 s.** the first t
ca90: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ime sqlite3_init
caa0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
cab0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c ked during the l
cac0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 ifetime of.** th
cad0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 e process, or if
cae0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 it is the first
caf0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e time sqlite3_in
cb00: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
cb10: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 voked.** followi
cb20: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c ng a call to sql
cb30: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
cb40: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 ^(Only an effe
cb50: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 ctive call.** of
cb60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
cb70: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 ize() does any i
cb80: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 nitialization.
cb90: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a All other calls.
cba0: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 ** are harmless
cbb0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
cbc0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
cbd0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 3_shutdown() is
cbe0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 an "effective" c
cbf0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 all if it is the
cc00: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 first.** call t
cc10: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
cc20: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c wn() since the l
cc30: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ast sqlite3_init
cc40: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c ialize(). ^(Onl
cc50: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 y.** an effectiv
cc60: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
cc70: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 3_shutdown() doe
cc80: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 s any deinitiali
cc90: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f zation..** All o
cca0: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 ther valid calls
ccb0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
ccc0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c down() are harml
ccd0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a ess no-ops.)^.**
cce0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
ccf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 initialize() int
cd00: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 erface is thread
cd10: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 safe, but sqlite
cd20: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 3_shutdown().**
cd30: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c is not. The sql
cd40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
cd50: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f interface must o
cd60: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 nly be called fr
cd70: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 om a.** single t
cd80: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e hread. All open
cd90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
cda0: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 ctions] must be
cdb0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a closed and all.*
cdc0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 * other SQLite r
cdd0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 esources must be
cde0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 deallocated pri
cdf0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a or to invoking.*
ce00: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f * sqlite3_shutdo
ce10: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e wn()..**.** Amon
ce20: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 g other things,
ce30: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c ^sqlite3_initial
ce40: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b ize() will invok
ce50: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f e.** sqlite3_os_
ce60: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 init(). Similar
ce70: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 ly, ^sqlite3_shu
ce80: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 tdown().** will
ce90: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f invoke sqlite3_o
cea0: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e s_end()..**.** ^
ceb0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
cec0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
ced0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
cee0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e _OK] on success.
cef0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 .** ^If for some
cf00: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 reason, sqlite3
cf10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
cf20: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 unable to initi
cf30: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 alize.** the lib
cf40: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 rary (perhaps it
cf50: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
cf60: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 locate a needed
cf70: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a resource such.**
cf80: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 as a mutex) it
cf90: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f returns an [erro
cfa0: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 r code] other th
cfb0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a an [SQLITE_OK]..
cfc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
cfd0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
cfe0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
cff0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
d000: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 many other.** SQ
d010: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
d020: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 so that an appli
d030: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 cation usually d
d040: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a oes not need to.
d050: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
d060: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
d070: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 irectly. For ex
d080: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f ample, [sqlite3_
d090: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 open()].** calls
d0a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
d0b0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c ize() so the SQL
d0c0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
d0d0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
d0e0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 y.** initialized
d0f0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f when [sqlite3_o
d100: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 pen()] is called
d110: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 if it has not b
d120: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a e initialized.**
d130: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 already. ^Howe
d140: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 ver, if SQLite i
d150: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
d160: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 the [SQLITE_OMIT
d170: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f _AUTOINIT].** co
d180: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
d190: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f n, then the auto
d1a0: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 matic calls to s
d1b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
d1c0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 e().** are omitt
d1d0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 ed and the appli
d1e0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c cation must call
d1f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
d200: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a ize() directly.*
d210: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 * prior to using
d220: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
d230: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f e interface. Fo
d240: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 r maximum portab
d250: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 ility,.** it is
d260: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
d270: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c applications al
d280: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 ways invoke sqli
d290: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
d2a0: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 .** directly pri
d2b0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 or to using any
d2c0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
d2d0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 erface. Future
d2e0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 releases.** of S
d2f0: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 QLite may requir
d300: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 e this. In othe
d310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 r words, the beh
d320: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a avior exhibited.
d330: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
d340: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
d350: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
d360: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 OINIT] might bec
d370: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 ome the.** defau
d380: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 lt behavior in s
d390: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 ome future relea
d3a0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a se of SQLite..**
d3b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
d3c0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e os_init() routin
d3d0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 e does operating
d3e0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 -system specific
d3f0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 .** initializati
d400: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 on of the SQLite
d410: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 library. The s
d420: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
d430: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 ** routine undoe
d440: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 s the effect of
d450: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
d460: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b ). Typical task
d470: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 s.** performed b
d480: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 y these routines
d490: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 include allocat
d4a0: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 ion or deallocat
d4b0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 ion.** of static
d4c0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 resources, init
d4d0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c ialization of gl
d4e0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a obal variables,.
d4f0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 ** setting up a
d500: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
d510: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 _vfs] module, or
d520: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 setting up.** a
d530: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
d540: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 ration using [sq
d550: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e lite3_config()].
d560: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
d570: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 cation should ne
d580: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 ver invoke eithe
d590: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
d5a0: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 t().** or sqlite
d5b0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 3_os_end() direc
d5c0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 tly. The applic
d5d0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c ation should onl
d5e0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 y invoke.** sqli
d5f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
d600: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 and sqlite3_shu
d610: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 tdown(). The sq
d620: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
d630: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
d640: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 called automatic
d650: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ally by sqlite3_
d660: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
d670: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 .** sqlite3_os_e
d680: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 nd() is called b
d690: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f y sqlite3_shutdo
d6a0: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 wn(). Appropria
d6b0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 te.** implementa
d6c0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 tions for sqlite
d6d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
d6e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
d6f0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e .** are built in
d700: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 to SQLite when i
d710: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f t is compiled fo
d720: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c r Unix, Windows,
d730: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 or OS/2..** Whe
d740: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 n [custom builds
d750: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 | built for oth
d760: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a er platforms].**
d770: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c (using the [SQL
d780: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 ITE_OS_OTHER=1]
d790: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 compile-time.**
d7a0: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c option) the appl
d7b0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 ication must sup
d7c0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 ply a suitable i
d7d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f mplementation fo
d7e0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f r.** sqlite3_os_
d7f0: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 init() and sqlit
d800: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e e3_os_end(). An
d810: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 application-sup
d820: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 plied.** impleme
d830: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
d840: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 e3_os_init() or
d850: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
d860: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 .** must return
d870: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
d880: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 uccess and some
d890: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 other [error cod
d8a0: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 e] upon.** failu
d8b0: 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 re..*/.SQLITE_AP
d8c0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e I int sqlite3_in
d8d0: 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a itialize(void);.
d8e0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
d8f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
d900: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
d910: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 I int sqlite3_os
d920: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c _init(void);.SQL
d930: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
d940: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
d950: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
d960: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
d970: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
d980: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 y.**.** The sqli
d990: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
d9a0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
d9b0: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f o make global co
d9c0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 nfiguration.** c
d9d0: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 hanges to SQLite
d9e0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e in order to tun
d9f0: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 e SQLite to the
da00: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
da10: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
da20: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 tion. The defau
da30: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
da40: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
da50: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c for most.** appl
da60: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 ications and so
da70: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
da80: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 usually not nece
da90: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a ssary. It is.**
daa0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 provided to sup
dab0: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 port rare applic
dac0: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 ations with unus
dad0: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ual needs..**.**
dae0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
daf0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
db00: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 is not threadsaf
db10: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 e. The applicat
db20: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 ion.** must insu
db30: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 re that no other
db40: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
db50: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 es are invoked b
db60: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 y other.** threa
db70: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 ds while sqlite3
db80: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e _config() is run
db90: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f ning. Furthermo
dba0: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 re, sqlite3_conf
dbb0: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ig().** may only
dbc0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f be invoked prio
dbd0: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 r to library ini
dbe0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e tialization usin
dbf0: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e g.** [sqlite3_in
dc00: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 itialize()] or a
dc10: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 fter shutdown by
dc20: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
dc30: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 wn()]..** ^If sq
dc40: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
dc50: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b s called after [
dc60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
dc70: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 ze()] and before
dc80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
dc90: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 tdown()] then it
dca0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c will return SQL
dcb0: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e ITE_MISUSE..** N
dcc0: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 ote, however, th
dcd0: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 at ^sqlite3_conf
dce0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
dcf0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
dd00: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
dd10: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
dd20: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
dd30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
dd40: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
dd50: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
dd60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
dd70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
dd80: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 [configuration
dd90: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
dda0: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
ddb0: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
ddc0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
ddd0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
dde0: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
ddf0: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
de00: 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 on the [configur
de10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a ation option].**
de20: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
de30: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 gument..**.** ^W
de40: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 hen a configurat
de50: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ion option is se
de60: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t, sqlite3_confi
de70: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c g() returns [SQL
de80: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 ITE_OK]..** ^If
de90: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e the option is un
dea0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 known or SQLite
deb0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 is unable to set
dec0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 the option.** t
ded0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
dee0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a returns a non-z
def0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
df00: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
df10: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 int sqlite3_conf
df20: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
df30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
df40: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
df50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
df60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
df70: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
df80: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
df90: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 make configurat
dfa0: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
dfb0: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f o a [database co
dfc0: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
dfd0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d interface is sim
dfe0: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ilar to.** [sqli
dff0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 te3_config()] ex
e000: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 cept that the ch
e010: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 anges apply to a
e020: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 single.** [data
e030: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
e040: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 (specified in t
e050: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
e060: 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 t)..**.** The se
e070: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
e080: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
e090: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
e0a0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 the.** [SQLITE_D
e0b0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
e0c0: 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f E | configuratio
e0d0: 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 n verb] - an int
e0e0: 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 eger code .** th
e0f0: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
e100: 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 t aspect of the
e110: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
e120: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 tion] is being c
e130: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 onfigured..** Su
e140: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
e150: 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ts vary dependin
e160: 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 g on the configu
e170: 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a ration verb..**.
e180: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
e190: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
e1a0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
e1b0: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 K if and only if
e1c0: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 .** the call is
e1d0: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 considered succe
e1e0: 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ssful..*/.SQLITE
e1f0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
e200: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 _db_config(sqlit
e210: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e e3*, int op, ...
e220: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
e230: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
e240: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a ation Routines.*
e250: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
e260: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
e270: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
e280: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 rface between SQ
e290: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d Lite.** and low-
e2a0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
e2b0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
e2c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ..**.** This obj
e2d0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f ect is used in o
e2e0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e nly one place in
e2f0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 the SQLite inte
e300: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e rface..** A poin
e310: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
e320: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
e330: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e t is the argumen
e340: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 t to.** [sqlite3
e350: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 _config()] when
e360: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
e370: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b n option is.** [
e380: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
e390: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 LLOC] or [SQLITE
e3a0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
e3b0: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 C]. .** By crea
e3c0: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 ting an instance
e3d0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a of this object.
e3e0: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 ** and passing i
e3f0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
e400: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f nfig]([SQLITE_CO
e410: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a NFIG_MALLOC]).**
e420: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 during configur
e430: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 ation, an applic
e440: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 ation can specif
e450: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
e460: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
e470: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 ation subsystem
e480: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 for SQLite to us
e490: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 e for all of its
e4a0: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f .** dynamic memo
e4b0: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 ry needs..**.**
e4c0: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 Note that SQLite
e4d0: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 comes with seve
e4e0: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 ral [built-in me
e4f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d mory allocators]
e500: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 .** that are per
e510: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 fectly adequate
e520: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c for the overwhel
e530: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 ming majority of
e540: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
e550: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f and that this o
e560: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 bject is only us
e570: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d eful to a tiny m
e580: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 inority of appli
e590: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 cations.** with
e5a0: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f specialized memo
e5b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
e5c0: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 quirements. Thi
e5d0: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 s object is.** a
e5e0: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 lso used during
e5f0: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 testing of SQLit
e600: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 e in order to sp
e610: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
e620: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
e630: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 llocator that si
e640: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f mulates memory o
e650: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e ut-of-memory con
e660: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 ditions in.** or
e670: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 der to verify th
e680: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 at SQLite recove
e690: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 rs gracefully fr
e6a0: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 om such.** condi
e6b0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tions..**.** The
e6c0: 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c xMalloc, xReall
e6d0: 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 oc, and xFree me
e6e0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 thods must work
e6f0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c like the.** mall
e700: 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 oc(), realloc()
e710: 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 and free() funct
e720: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 ions from the st
e730: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
e740: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 ..** ^SQLite gua
e750: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 rantees that the
e760: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
e770: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 to.** xRealloc
e780: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 is always a valu
e790: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 e returned by a
e7a0: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 prior call to xR
e7b0: 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 oundup..**.** xS
e7c0: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ize should retur
e7d0: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 n the allocated
e7e0: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 size of a memory
e7f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 allocation.** p
e800: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e reviously obtain
e810: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 ed from xMalloc
e820: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 or xRealloc. Th
e830: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
e840: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 .** is always at
e850: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 least as big as
e860: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 the requested s
e870: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c ize but may be l
e880: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 arger..**.** The
e890: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 xRoundup method
e8a0: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f returns what wo
e8b0: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 uld be the alloc
e8c0: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 ated size of.**
e8d0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
e8e0: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 ion given a part
e8f0: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 icular requested
e900: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d size. Most mem
e910: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
e920: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 s round up memor
e930: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 y allocations at
e940: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 least to the ne
e950: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f xt multiple.** o
e960: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 f 8. Some alloc
e970: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 ators round up t
e980: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 o a larger multi
e990: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 ple or to a powe
e9a0: 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 r of 2..** Every
e9b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
e9c0: 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e on request comin
e9d0: 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 g in through [sq
e9e0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a lite3_malloc()].
e9f0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 ** or [sqlite3_r
ea00: 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 ealloc()] first
ea10: 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 calls xRoundup.
ea20: 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 If xRoundup ret
ea30: 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 urns 0, .** that
ea40: 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 causes the corr
ea50: 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 esponding memory
ea60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 allocation to f
ea70: 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ail..**.** The x
ea80: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 Init method init
ea90: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f ializes the memo
eaa0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 ry allocator. (
eab0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 For example,.**
eac0: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 it might allocat
ead0: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 e any require mu
eae0: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c texes or initial
eaf0: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 ize internal dat
eb00: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e a.** structures.
eb10: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 The xShutdown
eb20: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 method is invoke
eb30: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 d (indirectly) b
eb40: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 y.** [sqlite3_sh
eb50: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 utdown()] and sh
eb60: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 ould deallocate
eb70: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 any resources ac
eb80: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e quired.** by xIn
eb90: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 it. The pAppDat
eba0: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 a pointer is use
ebb0: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 d as the only pa
ebc0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 rameter to.** xI
ebd0: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 nit and xShutdow
ebe0: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
ebf0: 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 holds the [SQLIT
ec00: 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
ec10: 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 ASTER] mutex whe
ec20: 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 n it invokes.**
ec30: 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 the xInit method
ec40: 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d , so the xInit m
ec50: 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 ethod need not b
ec60: 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 e threadsafe. T
ec70: 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 he.** xShutdown
ec80: 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 method is only c
ec90: 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 alled from [sqli
eca0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
ecb0: 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f so it does.** no
ecc0: 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 t need to be thr
ecd0: 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 eadsafe either.
ece0: 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d For all other m
ecf0: 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a ethods, SQLite.*
ed00: 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c * holds the [SQL
ed10: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
ed20: 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c _MEM] mutex as l
ed30: 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 ong as the.** [S
ed40: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
ed50: 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 STATUS] configur
ed60: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
ed70: 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 turned on (which
ed80: 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 .** it is by def
ed90: 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 ault) and so the
eda0: 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 methods are aut
edb0: 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 omatically seria
edc0: 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 lized..** Howeve
edd0: 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f r, if [SQLITE_CO
ede0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 NFIG_MEMSTATUS]
edf0: 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 is disabled, the
ee00: 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d n the other.** m
ee10: 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 ethods must be t
ee20: 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 hreadsafe or els
ee30: 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e e make their own
ee40: 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f arrangements fo
ee50: 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 r.** serializati
ee60: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 on..**.** SQLite
ee70: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f will never invo
ee80: 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 ke xInit() more
ee90: 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 than once withou
eea0: 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 t an intervening
eeb0: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 .** call to xShu
eec0: 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 tdown()..*/.type
eed0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
eee0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 e3_mem_methods s
eef0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
ef00: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
ef10: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b e3_mem_methods {
ef20: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c . void *(*xMall
ef30: 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 oc)(int);
ef40: 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f /* Memory allo
ef50: 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 cation function
ef60: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 */. void (*xFre
ef70: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
ef80: 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 /* Free a pr
ef90: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a ior allocation *
efa0: 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 /. void *(*xRea
efb0: 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 lloc)(void*,int)
efc0: 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 ; /* Resize an
efd0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
efe0: 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 int (*xSize)(voi
eff0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
f000: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a * Return the siz
f010: 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 e of an allocati
f020: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 on */. int (*xR
f030: 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 oundup)(int);
f040: 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 /* Round
f050: 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 up request size
f060: 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 to allocation si
f070: 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 ze */. int (*xI
f080: 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 nit)(void*);
f090: 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 /* Initia
f0a0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
f0b0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
f0c0: 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 oid (*xShutdown)
f0d0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a (void*); /*
f0e0: 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 Deinitialize th
f0f0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
f100: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 or */. void *pA
f110: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
f120: 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 /* Argume
f130: 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e nt to xInit() an
f140: 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f d xShutdown() */
f150: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
f160: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 REF: Configurati
f170: 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 on Options.** KE
f180: 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 YWORDS: {configu
f190: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a ration option}.*
f1a0: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
f1b0: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
f1c0: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
f1d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
f1e0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
f1f0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
f200: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
f210: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
f220: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
f230: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
f240: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
f250: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
f260: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
f270: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
f280: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
f290: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
f2a0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
f2b0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
f2c0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
f2d0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
f2e0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
f2f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
f300: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
f310: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
f320: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
f330: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
f340: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
f350: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
f360: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
f370: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
f380: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
f390: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
f3a0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
f3b0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
f3c0: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
f3d0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d G_SINGLETHREAD]]
f3e0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
f3f0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c IG_SINGLETHREAD<
f400: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
f410: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
f420: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
f430: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
f440: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
f450: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
f460: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 Single-thread.
f470: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
f480: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 it disables.**
f490: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
f4a0: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
f4b0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
f4c0: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
f4d0: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
f4e0: 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 e thread. ^If
f4f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
f500: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
f510: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
f520: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
f530: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
f540: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
f550: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
f560: 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 ossible to chang
f570: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
f580: 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 mode] from its
f590: 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 default.** value
f5a0: 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 of Single-threa
f5b0: 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 d and so [sqlite
f5c0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
f5d0: 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c return .** [SQL
f5e0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 ITE_ERROR] if ca
f5f0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 lled with the SQ
f600: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
f610: 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 LETHREAD.** conf
f620: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
f630: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
f640: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
f650: 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 TITHREAD]] <dt>S
f660: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
f670: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a TITHREAD</dt>.**
f680: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
f690: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
f6a0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
f6b0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
f6c0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
f6d0: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d mode] to Multi-
f6e0: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 thread. In othe
f6f0: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 r words, it disa
f700: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
f710: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
f720: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
f730: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
f740: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
f750: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
f760: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
f770: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
f780: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
f790: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
f7a0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
f7b0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
f7c0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
f7d0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
f7e0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
f7f0: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
f800: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
f810: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
f820: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
f830: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
f840: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
f850: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
f860: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
f870: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
f880: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 . ^If SQLite is
f890: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
f8a0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
f8b0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
f8c0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
f8d0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
f8e0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
f8f0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
f900: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d o set the Multi-
f910: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
f920: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
f930: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f940: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
f950: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
f960: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
f970: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
f980: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e _MULTITHREAD con
f990: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
f9a0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
f9b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
f9c0: 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 RIALIZED]] <dt>S
f9d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
f9e0: 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 IALIZED</dt>.**
f9f0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
fa00: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
fa10: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
fa20: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
fa30: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
fa40: 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 mode] to Seriali
fa50: 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f zed. In other wo
fa60: 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e rds, this option
fa70: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 enables.** all
fa80: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e mutexes includin
fa90: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a g the recursive.
faa0: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 ** mutexes on [d
fab0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
fac0: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
fad0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
fae0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 ects..** In this
faf0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 mode (which is
fb00: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e the default when
fb10: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
fb20: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c led with.** [SQL
fb30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
fb40: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ]) the SQLite li
fb50: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c brary will itsel
fb60: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 f serialize acce
fb70: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 ss.** to [databa
fb80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
fb90: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
fba0: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 atements] so tha
fbb0: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 t the.** applica
fbc0: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 tion is free to
fbd0: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 use the same [da
fbe0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
fbf0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d n] or the.** sam
fc00: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
fc10: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 ement] in differ
fc20: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 ent threads at t
fc30: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
fc40: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
fc50: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
fc60: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
fc70: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
fc80: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
fc90: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
fca0: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
fcb0: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
fcc0: 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a set the Serializ
fcd0: 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
fce0: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
fcf0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
fd00: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
fd10: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
fd20: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
fd30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
fd40: 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 IALIZED configur
fd50: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
fd60: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
fd70: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
fd80: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
fd90: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a FIG_MALLOC</dt>.
fda0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
fdb0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
fdc0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
fdd0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
fde0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
fdf0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
fe00: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
fe10: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
fe20: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
fe30: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
fe40: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f e low-level memo
fe50: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
fe60: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
fe70: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a d in place of.**
fe80: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
fe90: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
fea0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
feb0: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b e.)^ ^SQLite mak
fec0: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 es.** its own pr
fed0: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
fee0: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
fef0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
ff00: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
ff10: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
ff20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
ff30: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c ] call returns.<
ff40: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
ff50: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
ff60: 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
ff70: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
ff80: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OC</dt>.** <dd>
ff90: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^(This option ta
ffa0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
ffb0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
ffc0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
ffd0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
ffe0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
fff0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
10000 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 e. The [sqlite3
10010 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a _mem_methods].**
10020 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
10030 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
10040 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
10050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
10060 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a n routines.)^.**
10070 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
10080 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
10090 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
100a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
100b0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
100c0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
100d0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
100e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
100f0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
10100 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
10110 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
10120 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
10130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
10140 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c STATUS]] <dt>SQL
10150 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
10160 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATUS</dt>.** <dd
10170 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 > ^This option t
10180 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 akes single argu
10190 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
101a0 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 , interpreted as
101b0 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 a .** boolean,
101c0 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 which enables or
101d0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f disables the co
101e0 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f llection of memo
101f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a ry allocation .*
10200 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 * statistics. ^(
10210 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f When memory allo
10220 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
10230 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 s are disabled,
10240 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e the .** followin
10250 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 g SQLite interfa
10260 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f ces become non-o
10270 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 perational:.**
10280 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
10290 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
102a0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 used()].** <li
102b0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
102c0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a y_highwater()].*
102d0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
102e0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
102f0 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e t64()].** <li>
10300 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
10310 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e ()].** </ul>)^
10320 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f .** ^Memory allo
10330 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
10340 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 s are enabled by
10350 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 default unless
10360 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d SQLite is.** com
10370 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 piled with [SQLI
10380 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 TE_DEFAULT_MEMST
10390 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 ATUS]=0 in which
103a0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 case memory.**
103b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
103c0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c stics are disabl
103d0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
103e0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
103f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
10400 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 RATCH]] <dt>SQLI
10410 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
10420 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e H</dt>.** <dd> ^
10430 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
10440 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
10450 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
10460 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 t SQLite can use
10470 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 for.** scratch
10480 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 memory. There a
10490 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
104a0 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 ts: A pointer a
104b0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 n 8-byte.** alig
104c0 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 ned memory buffe
104d0 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 r from which the
104e0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
104f0 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 ions will be.**
10500 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 drawn, the size
10510 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 of each scratch
10520 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c allocation (sz),
10530 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 .** and the maxi
10540 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 mum number of sc
10550 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
10560 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a s (N). The sz.*
10570 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 * argument must
10580 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 be a multiple of
10590 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 16..** The firs
105a0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 t argument must
105b0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
105c0 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 an 8-byte aligne
105d0 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 d buffer.** of a
105e0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
105f0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
10600 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
10610 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 e no more than t
10620 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 wo scratch buffe
10630 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 rs per thread.
10640 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 So.** N should b
10650 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 e set to twice t
10660 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 he expected maxi
10670 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 mum number of th
10680 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 reads..** ^SQLit
10690 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 e will never req
106a0 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 uire a scratch b
106b0 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f uffer that is mo
106c0 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d re than 6.** tim
106d0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
106e0 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 page size. ^If S
106f0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 QLite needs need
10700 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 s additional.**
10710 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 scratch memory b
10720 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
10730 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 ovided by this c
10740 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
10750 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 ion, then .** [s
10760 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
10770 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f will be used to
10780 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f obtain the memo
10790 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a ry needed.</dd>.
107a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
107b0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
107c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
107d0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 FIG_PAGECACHE</d
107e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
107f0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
10800 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
10810 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
10820 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
10830 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
10840 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 page cache with
10850 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 the default pag
10860 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
10870 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 tation. .** Thi
10880 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
10890 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 should not be us
108a0 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 ed if an applica
108b0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 tion-define page
108c0 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d .** cache implem
108d0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 entation is load
108e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c ed using the SQL
108f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
10900 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 E2 option..** Th
10910 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
10920 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
10930 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 option: A pointe
10940 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 r to 8-byte alig
10950 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 ned.** memory, t
10960 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 he size of each
10970 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 page buffer (sz)
10980 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 , and the number
10990 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a of pages (N)..*
109a0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e * The sz argumen
109b0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 t should be the
109c0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 size of the larg
109d0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 est database pag
109e0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 e.** (a power of
109f0 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 two between 512
10a00 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 and 32768) plus
10a10 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 a little extra
10a20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 for each.** page
10a30 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 header. ^The p
10a40 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 age header size
10a50 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 is 20 to 40 byte
10a60 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a s depending on.*
10a70 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 * the host archi
10a80 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 tecture. ^It is
10a90 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 harmless, apart
10aa0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 from the wasted
10ab0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d memory,.** to m
10ac0 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 ake sz a little
10ad0 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 too large. The
10ae0 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e first.** argumen
10af0 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 t should point t
10b00 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 o an allocation
10b10 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
10b20 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
10b30 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c ..** ^SQLite wil
10b40 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 l use the memory
10b50 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 provided by the
10b60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
10b70 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a to satisfy its.*
10b80 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 * memory needs f
10b90 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 or the first N p
10ba0 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 ages that it add
10bb0 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 s to cache. ^If
10bc0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 additional.** p
10bd0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 age cache memory
10be0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e is needed beyon
10bf0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
10c00 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f ed by this optio
10c10 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 n, then.** SQLit
10c20 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 e goes to [sqlit
10c30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 e3_malloc()] for
10c40 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 the additional
10c50 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a storage space..*
10c60 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e * The pointer in
10c70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
10c80 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 ent must.** be a
10c90 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
10ca0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 yte boundary or
10cb0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
10cc0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ior of SQLite.**
10cd0 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e will be undefin
10ce0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ed.</dd>.**.** [
10cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 [SQLITE_CONFIG_H
10d00 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAP]] <dt>SQLITE
10d10 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 _CONFIG_HEAP</dt
10d20 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
10d30 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
10d40 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
10d50 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
10d60 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
10d70 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
10d80 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c ynamic memory al
10d90 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 location needs b
10da0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 eyond those prov
10db0 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b ided.** for by [
10dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
10dd0 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 RATCH] and [SQLI
10de0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
10df0 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 CHE]..** There a
10e00 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
10e10 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c ts: An 8-byte al
10e20 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f igned pointer to
10e30 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 the memory,.**
10e40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
10e50 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 tes in the memor
10e60 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 y buffer, and th
10e70 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
10e80 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 tion size..** ^I
10e90 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e f the first poin
10ea0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
10eb0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c pointer) is NULL
10ec0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 , then SQLite re
10ed0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e verts.** to usin
10ee0 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 g its default me
10ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 mory allocator (
10f00 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
10f10 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 c() implementati
10f20 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 on),.** undoing
10f30 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 any prior invoca
10f40 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f tion of [SQLITE_
10f50 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 CONFIG_MALLOC].
10f60 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f ^If the.** memo
10f70 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f ry pointer is no
10f80 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 t NULL and eithe
10f90 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 r [SQLITE_ENABLE
10fa0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 _MEMSYS3] or.**
10fb0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
10fc0 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 EMSYS5] are defi
10fd0 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c ned, then the al
10fe0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 ternative memory
10ff0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 .** allocator is
11000 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 engaged to hand
11010 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 le all of SQLite
11020 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
11030 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 ion needs..** Th
11040 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
11050 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
11060 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 ter) must be ali
11070 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
11080 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 e.** boundary or
11090 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
110a0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 vior of SQLite w
110b0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 ill be undefined
110c0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d ..** The minimum
110d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
110e0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a is capped at 2*
110f0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 *12. Reasonable
11100 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 values.** for th
11110 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
11120 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a tion size are 2*
11130 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e *5 through 2**8.
11140 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
11150 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
11160 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 X]] <dt>SQLITE_C
11170 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e ONFIG_MUTEX</dt>
11180 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
11190 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
111a0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
111b0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
111c0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
111d0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
111e0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
111f0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
11200 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
11210 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
11220 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
11230 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f utex routines to
11240 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 be used in plac
11250 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 e.** the mutex r
11260 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
11270 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 to SQLite.)^ ^S
11280 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
11290 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e py of the.** con
112a0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
112b0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
112c0 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 ds] structure be
112d0 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f fore the call to
112e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
112f0 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 fig()] returns.
11300 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
11310 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
11320 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
11330 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
11340 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
11350 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
11360 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
11370 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
11380 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
11390 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
113a0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
113b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
113c0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
113d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
113e0 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 _MUTEX configura
113f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
11400 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
11410 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
11420 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
11430 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d ONFIG_GETMUTEX]]
11440 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
11450 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e IG_GETMUTEX</dt>
11460 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
11470 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
11480 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
11490 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
114a0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
114b0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
114c0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
114d0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
114e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
114f0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a utex_methods].**
11500 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
11510 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
11520 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
11530 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 mutex routines.)
11540 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
11550 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
11560 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
11570 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 ault mutex alloc
11580 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
11590 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
115a0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d used to track m
115b0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 utex usage for p
115c0 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 erformance.** pr
115d0 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 ofiling or testi
115e0 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ng, for example.
115f0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 ^If SQLite is
11600 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
11610 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
11620 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
11630 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
11640 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
11650 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ion then.** the
11660 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 entire mutexing
11670 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 subsystem is omi
11680 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 tted from the bu
11690 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 ild and hence ca
116a0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
116b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 e3_config()] wit
116c0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
116d0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e FIG_GETMUTEX con
116e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
116f0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
11700 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
11710 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
11720 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
11730 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 ASIDE]] <dt>SQLI
11740 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
11750 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
11760 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
11770 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e akes two argumen
11780 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e ts that determin
11790 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a e the default.**
117a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
117b0 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 on for the looka
117c0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f side memory allo
117d0 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a cator on each.**
117e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
117f0 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 ction]. The fir
11800 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 st argument is t
11810 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
11820 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
11830 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 fer slot and the
11840 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e second is the n
11850 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
11860 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 s allocated to e
11870 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
11880 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 nection.)^ ^(Th
11890 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
118a0 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 he.** <i>default
118b0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 </i> lookaside s
118c0 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 ize. The [SQLITE
118d0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
118e0 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 IDE].** verb to
118f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
11900 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 ig()] can be use
11910 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 d to change the
11920 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e lookaside.** con
11930 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e figuration on in
11940 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 dividual connect
11950 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ions.)^ </dd>.**
11960 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
11970 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 FIG_PCACHE2]] <d
11980 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
11990 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 PCACHE2</dt>.**
119a0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
119b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
119c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
119d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
119e0 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f .** an [sqlite3_
119f0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
11a00 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f object. This o
11a10 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 bject specifies
11a20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
11a30 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 to a custom pag
11a40 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
11a50 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 tation.)^ ^SQLi
11a60 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
11a70 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 of the.** object
11a80 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 and uses it for
11a90 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
11aa0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c ry allocations.<
11ab0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
11ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
11ad0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 ACHE2]] <dt>SQLI
11ae0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
11af0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHE2</dt>.** <dd
11b00 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
11b10 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
11b20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
11b30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
11b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 .** [sqlite3_pca
11b50 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
11b60 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f ject. SQLite co
11b70 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 pies of the curr
11b80 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 ent.** page cach
11b90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
11ba0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 into that objec
11bb0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a t.)^ </dd>.**.**
11bc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
11bd0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _LOG]] <dt>SQLIT
11be0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 E_CONFIG_LOG</dt
11bf0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 >.** <dd> ^The S
11c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
11c10 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
11c20 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 o arguments: a p
11c30 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 ointer to a.** f
11c40 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 unction with a c
11c50 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 all signature of
11c60 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 void(*)(void*,i
11c70 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c nt,const char*),
11c80 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 .** and a point
11c90 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 er to void. ^If
11ca0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 the function poi
11cb0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
11cc0 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b , it is.** invok
11cd0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
11ce0 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 og()] to process
11cf0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 each logging ev
11d00 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ent. ^If the.**
11d10 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
11d20 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b r is NULL, the [
11d30 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 sqlite3_log()] i
11d40 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 nterface becomes
11d50 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 a no-op..** ^Th
11d60 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 e void pointer t
11d70 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e hat is the secon
11d80 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 d argument to SQ
11d90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
11da0 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 is.** passed thr
11db0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 ough as the firs
11dc0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
11dd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
11de0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a efined logger.**
11df0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 function whenev
11e00 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e er that function
11e10 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 is invoked. ^T
11e20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
11e30 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f ter to.** the lo
11e40 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 gger function is
11e50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 a copy of the f
11e60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
11e70 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 o the correspond
11e80 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
11e90 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 log()] call and
11ea0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 is intended to b
11eb0 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 e a [result code
11ec0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 ] or an.** [exte
11ed0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
11ee0 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 ]. ^The third p
11ef0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 arameter passed
11f00 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 to the logger is
11f10 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 .** log message
11f20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 after formatting
11f30 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e via [sqlite3_sn
11f40 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 printf()]..** Th
11f50 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 e SQLite logging
11f60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
11f70 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 t reentrant; the
11f80 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e logger function
11f90 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 .** supplied by
11fa0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
11fb0 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 must not invoke
11fc0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
11fd0 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 face..** In a mu
11fe0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 lti-threaded app
11ff0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 lication, the ap
12000 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
12010 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
12020 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 tion must be thr
12030 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a eadsafe. </dd>.*
12040 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
12050 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 NFIG_URI]] <dt>S
12060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
12070 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 .** <dd> This op
12080 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
12090 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 gle argument of
120a0 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e type int. If non
120b0 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 -zero, then.** U
120c0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
120d0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e lobally enabled.
120e0 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 If the paramete
120f0 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 r is zero, then
12100 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 URI handling.**
12110 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 is globally disa
12120 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e bled. If URI han
12130 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
12140 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 y enabled, all f
12150 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 ilenames.** pass
12160 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ed to [sqlite3_o
12170 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
12180 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 _open_v2()], [sq
12190 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
121a0 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 or.** specified
121b0 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 as part of [ATTA
121c0 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 CH] commands are
121d0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
121e0 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 URIs, regardless
121f0 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f .** of whether o
12200 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 r not the [SQLIT
12210 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
12220 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
12230 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
12240 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
12250 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 d. If it is glob
12260 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 ally disabled, f
12270 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 ilenames are.**
12280 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 only interpreted
12290 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 as URIs if the
122a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 SQLITE_OPEN_URI
122b0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
122c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
122d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
122e0 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c pened. By defaul
122f0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 t, URI handling
12300 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 is globally.** d
12310 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 isabled. The def
12320 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 ault value may b
12330 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d e changed by com
12340 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a piling with the.
12350 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 ** [SQLITE_USE_U
12360 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e RI] symbol defin
12370 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ed..**.** [[SQLI
12380 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
12390 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ]] [[SQLITE_CONF
123a0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a IG_GETPCACHE]].*
123b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
123c0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 FIG_PCACHE and S
123d0 51 4c 49 54 45 5f 43 4f 4e 46 4e 49 47 5f 47 45 QLITE_CONFNIG_GE
123e0 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 TPCACHE.** <dd>
123f0 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 These options ar
12400 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 e obsolete and s
12410 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 hould not be use
12420 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a d by new code..*
12430 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 * They are retai
12440 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ned for backward
12450 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
12460 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f but are now no-o
12470 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a ps..** </dl>.*/.
12480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
12490 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
124a0 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f AD 1 /* nil */
124b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
124c0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
124d0 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a AD 2 /* nil *
124e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
124f0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
12500 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 ED 3 /* nil
12510 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
12520 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
12530 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 4 /* sql
12540 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
12550 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
12560 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
12570 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 LLOC 5 /* s
12580 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
12590 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
125a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
125b0 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a ATCH 6 /*
125c0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
125d0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
125e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
125f0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 AGECACHE 7
12600 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
12610 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
12620 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
12630 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 _HEAP 8
12640 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
12650 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a nByte, int min *
12660 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
12670 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
12680 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c S 9 /* bool
12690 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ean */.#define S
126a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
126b0 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a EX 10 /*
126c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
126d0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
126e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
126f0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 _GETMUTEX 11
12700 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
12710 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f ex_methods* */./
12720 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c * previously SQL
12730 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b ITE_CONFIG_CHUNK
12740 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 ALLOC 12 which i
12750 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f s now unused. */
12760 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .#define SQLITE
12770 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
12780 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 E 13 /* int
12790 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
127a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
127b0 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a CHE 14 /*
127c0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e no-op */.#defin
127d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
127e0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
127f0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
12800 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
12810 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 IG_LOG
12820 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 16 /* xFunc, vo
12830 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
12840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
12850 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 17 /*
12860 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
12870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
12880 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f ACHE2 18 /
12890 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
128a0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 _methods2* */.#d
128b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
128c0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 FIG_GETPCACHE2
128d0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 19 /* sqlite3_
128e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a pcache_methods2*
128f0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
12900 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
12910 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 nnection Configu
12920 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
12930 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
12940 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
12950 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
12960 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
12970 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
12980 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
12990 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
129a0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
129b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
129c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
129d0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
129e0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
129f0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
12a00 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
12a10 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
12a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
12a30 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
12a40 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
12a50 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
12a60 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
12a70 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
12a80 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
12a90 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 fig()] to make s
12aa0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ure that.** the
12ab0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 call worked. ^T
12ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 he [sqlite3_db_c
12ad0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
12ae0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
12af0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
12b00 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
12b10 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
12b20 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
12b30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
12b40 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
12b50 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
12b60 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
12b70 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
12b80 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
12b90 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 tion takes three
12ba0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
12bb0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
12bc0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f mine the .** [lo
12bd0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
12be0 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
12bf0 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 uration for the
12c00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
12c10 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 tion]..** ^The f
12c20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 irst argument (t
12c30 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
12c40 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 er to [sqlite3_d
12c50 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 b_config()] is a
12c60 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
12c70 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
12c80 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 o use for lookas
12c90 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e ide memory..** ^
12ca0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
12cb0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c nt after the SQL
12cc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
12cd0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d KASIDE verb.** m
12ce0 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 ay be NULL in wh
12cf0 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 ich case SQLite
12d00 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 will allocate th
12d10 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 e.** lookaside b
12d20 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 uffer itself usi
12d30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ng [sqlite3_mall
12d40 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f oc()]. ^The seco
12d50 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
12d60 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
12d70 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
12d80 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 fer slot. ^The
12d90 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
12da0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
12db0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 ** slots. The s
12dc0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
12dd0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
12de0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
12df0 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 greater than.**
12e00 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 or equal to the
12e10 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 product of the s
12e20 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 econd and third
12e30 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 arguments. The
12e40 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 buffer.** must b
12e50 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
12e60 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 8-byte boundary.
12e70 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 ^If the second
12e80 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
12e90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
12ea0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 LOOKASIDE is not
12eb0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 a multiple of 8
12ec0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c , it is internal
12ed0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f ly.** rounded do
12ee0 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 wn to the next s
12ef0 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 maller multiple
12f00 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f of 8. ^(The loo
12f10 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a kaside memory.**
12f20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
12f30 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f or a database co
12f40 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c nnection can onl
12f50 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 y be changed whe
12f60 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 n that.** connec
12f70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 tion is not curr
12f80 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b ently using look
12f90 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 aside memory, or
12fa0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a in other words.
12fb0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 ** when the "cur
12fc0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 rent value" retu
12fd0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
12fe0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 te3_db_status](D
12ff0 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ,[SQLITE_CONFIG_
13000 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 LOOKASIDE],...)
13010 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 is zero..** Any
13020 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 attempt to chang
13030 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 e the lookaside
13040 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 memory configura
13050 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 tion when lookas
13060 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 ide.** memory is
13070 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 in use leaves t
13080 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
13090 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 unchanged and r
130a0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 eturns .** [SQLI
130b0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e TE_BUSY].)^</dd>
130c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
130d0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
130e0 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c E_FKEY</dt>.** <
130f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
13100 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
13110 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
13120 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 e enforcement of
13130 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
13140 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 constraints].
13150 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
13160 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
13170 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
13180 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
13190 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
131a0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
131b0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 ble FK enforceme
131c0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 nt,.** positive
131d0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 to enable FK enf
131e0 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 orcement or nega
131f0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b tive to leave FK
13200 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 enforcement.**
13210 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
13220 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
13230 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
13240 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
13250 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
13260 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
13270 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
13280 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 FK enforcement i
13290 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 s off or on.** f
132a0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
132b0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
132c0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
132d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
132e0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
132f0 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 e the FK enforce
13300 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 ment setting is
13310 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
13320 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
13330 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
13340 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
13350 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e R</dt>.** <dd> ^
13360 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
13370 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
13380 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 disable [CREATE
13390 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
133a0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 ers]..** There s
133b0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
133c0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
133d0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
133e0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
133f0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
13400 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 0 to disable tri
13410 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 ggers,.** positi
13420 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 ve to enable tri
13430 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 ggers or negativ
13440 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
13450 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 etting unchanged
13460 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
13470 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
13480 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
13490 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
134a0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
134b0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
134c0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 whether trigger
134d0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f s are disabled o
134e0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c r enabled.** fol
134f0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
13500 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
13510 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
13520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
13530 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
13540 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 the trigger sett
13550 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
13560 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
13570 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 **.** </dl>.*/.#
13580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
13590 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
135a0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 1001 /*
135b0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f void* int int */
135c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
135d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
135e0 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f FKEY 1002 /
135f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 * int int* */.#d
13600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
13610 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 ONFIG_ENABLE_TRI
13620 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 GGER 1003 /* i
13630 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a nt int* */.../*.
13640 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
13650 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
13660 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
13670 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 odes.**.** ^The
13680 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
13690 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
136a0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
136b0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
136c0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
136d0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
136e0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 re of SQLite. ^T
136f0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
13700 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 lt.** codes are
13710 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
13720 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ult for historic
13730 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 al compatibility
13740 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
13750 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
13760 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
13770 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
13780 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
13790 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
137a0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a sert Rowid.**.**
137b0 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 ^Each entry in
137c0 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 an SQLite table
137d0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
137e0 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e bit signed.** in
137f0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 teger key called
13800 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 the [ROWID | "r
13810 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 owid"]. ^The row
13820 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
13830 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
13840 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
13850 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
13860 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
13870 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
13880 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
13890 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
138a0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
138b0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a d columns. ^If.*
138c0 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
138d0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
138e0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
138f0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
13900 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
13910 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
13920 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
13930 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
13940 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 eturns the [rowi
13950 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 d] of the most r
13960 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 ecent.** success
13970 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 ful [INSERT] int
13980 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
13990 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 rom the [databas
139a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
139b0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
139c0 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 gument. ^As of
139d0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
139e0 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 .7.7, this routi
139f0 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 nes.** records t
13a00 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 he last insert r
13a10 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 owid of both ord
13a20 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 inary tables and
13a30 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 [virtual tables
13a40 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 ]..** ^If no suc
13a50 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
13a60 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
13a70 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 ccurred on that
13a80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13a90 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
13aa0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 urned..**.** ^(I
13ab0 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
13ac0 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
13ad0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 igger or within
13ae0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a [virtual table
13af0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 ].** method, the
13b00 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 n this routine w
13b10 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b ill return the [
13b20 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e rowid] of the in
13b30 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 serted.** row as
13b40 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
13b50 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 gger or virtual
13b60 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 table method is
13b70 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 running..** But
13b80 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 once the trigger
13b90 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c or virtual tabl
13ba0 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 e method ends, t
13bb0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
13bc0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f d .** by this ro
13bd0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f utine reverts to
13be0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 what it was bef
13bf0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ore the trigger
13c00 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 or virtual.** ta
13c10 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e ble method began
13c20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 .)^.**.** ^An [I
13c30 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c NSERT] that fail
13c40 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 s due to a const
13c50 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 raint violation
13c60 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 is not a.** succ
13c70 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 essful [INSERT]
13c80 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 and does not cha
13c90 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 nge the value re
13ca0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a turned by this.*
13cb0 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 * routine. ^Thu
13cc0 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c s INSERT OR FAIL
13cd0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f , INSERT OR IGNO
13ce0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f RE, INSERT OR RO
13cf0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 LLBACK,.** and I
13d00 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d NSERT OR ABORT m
13d10 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 ake no changes t
13d20 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c o the return val
13d30 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f ue of this.** ro
13d40 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 utine when their
13d50 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 insertion fails
13d60 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 . ^(When INSERT
13d70 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 OR REPLACE.** e
13d80 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 ncounters a cons
13d90 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
13da0 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 , it does not fa
13db0 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 il. The.** INSE
13dc0 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 RT continues to
13dd0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 completion after
13de0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 deleting rows t
13df0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 hat caused.** th
13e00 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f e constraint pro
13e10 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f blem so INSERT O
13e20 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 R REPLACE will a
13e30 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 lways change.**
13e40 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
13e50 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
13e60 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 ce.)^.**.** ^For
13e70 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
13e80 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 this routine, a
13e90 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f n [INSERT] is co
13ea0 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 nsidered to.** b
13eb0 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 e successful eve
13ec0 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 n if it is subse
13ed0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 quently rolled b
13ee0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ack..**.** This
13ef0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 function is acce
13f00 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 ssible to SQL st
13f10 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 atements via the
13f20 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 .** [last_insert
13f30 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e _rowid() SQL fun
13f40 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
13f50 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
13f60 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 ad performs a ne
13f70 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 w [INSERT] on th
13f80 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 e same.** databa
13f90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 se connection wh
13fa0 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ile the [sqlite3
13fb0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
13fc0 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f id()].** functio
13fd0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 n is running and
13fe0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 thus changes th
13ff0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 e last insert [r
14000 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 owid],.** then t
14010 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
14020 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 d by [sqlite3_la
14030 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
14040 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 )] is.** unpredi
14050 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 ctable and might
14060 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 not equal eithe
14070 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 r the old or the
14080 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 new.** last ins
14090 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a ert [rowid]..*/.
140a0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
140b0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
140c0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
140d0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f id(sqlite3*);../
140e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
140f0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 ount The Number
14100 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
14110 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
14120 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
14130 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 e number of data
14140 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 base rows that w
14150 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f ere changed.** o
14160 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 r inserted or de
14170 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 leted by the mos
14180 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c t recently compl
14190 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 eted SQL stateme
141a0 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 nt.** on the [da
141b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
141c0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 n] specified by
141d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
141e0 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 ter..** ^(Only c
141f0 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 hanges that are
14200 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 directly specifi
14210 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 ed by the [INSER
14220 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a T], [UPDATE],.**
14230 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 or [DELETE] sta
14240 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 tement are count
14250 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 ed. Auxiliary c
14260 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
14270 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 .** triggers or
14280 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 [foreign key act
14290 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f ions] are not co
142a0 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 unted.)^ Use the
142b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 .** [sqlite3_tot
142c0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 al_changes()] fu
142d0 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 nction to find t
142e0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 he total number
142f0 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e of changes.** in
14300 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 cluding changes
14310 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 caused by trigge
14320 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b rs and foreign k
14330 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a ey actions..**.*
14340 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 * ^Changes to a
14350 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 view that are si
14360 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 mulated by an [I
14370 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
14380 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f r].** are not co
14390 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 unted. Only rea
143a0 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 l table changes
143b0 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a are counted..**.
143c0 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e ** ^(A "row chan
143d0 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 ge" is a change
143e0 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 to a single row
143f0 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c of a single tabl
14400 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 e.** caused by a
14410 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 n INSERT, DELETE
14420 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 , or UPDATE stat
14430 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 ement. Rows tha
14440 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 t.** are changed
14450 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 as side effects
14460 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f of [REPLACE] co
14470 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
14480 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b ion,.** rollback
14490 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 , ABORT processi
144a0 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d ng, [DROP TABLE]
144b0 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 , or by any othe
144c0 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 r.** mechanisms
144d0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 do not count as
144e0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 direct row chang
144f0 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 es.)^.**.** A "t
14500 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 rigger context"
14510 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 is a scope of ex
14520 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 ecution that beg
14530 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 ins and.** ends
14540 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 with the script
14550 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 of a [CREATE TRI
14560 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e GGER | trigger].
14570 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 .** Most SQL st
14580 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 atements are.**
14590 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 evaluated outsid
145a0 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 e of any trigger
145b0 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 . This is the "
145c0 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 top level".** tr
145d0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 igger context.
145e0 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 If a trigger fir
145f0 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 es from the top
14600 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 level, a.** new
14610 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 trigger context
14620 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 is entered for t
14630 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 he duration of t
14640 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 hat one.** trigg
14650 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 er. Subtriggers
14660 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 create subconte
14670 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 xts for their du
14680 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ration..**.** ^C
14690 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
146a0 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 exec()] or [sqli
146b0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 te3_step()] recu
146c0 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 rsively does.**
146d0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 not create a new
146e0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
146f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 ..**.** ^This fu
14700 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
14710 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 he number of dir
14720 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 ect row changes
14730 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 in the.** most r
14740 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 ecent INSERT, UP
14750 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 DATE, or DELETE
14760 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
14770 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 the same.** tri
14780 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a gger context..**
14790 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 .** ^Thus, when
147a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
147b0 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 top level, this
147c0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
147d0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
147e0 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 f changes in the
147f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
14800 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
14810 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 DELETE.** that a
14820 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 lso occurred at
14830 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 the top level.
14840 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 ^(Within the bod
14850 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a y of a trigger,.
14860 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 ** the sqlite3_c
14870 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 hanges() interfa
14880 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 ce can be called
14890 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
148a0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 ber of.** change
148b0 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 s in the most re
148c0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
148d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
148e0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 or DELETE.** st
148f0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
14900 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 he body of the s
14910 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 ame trigger..**
14920 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d However, the num
14930 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 ber returned doe
14940 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
14950 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 anges.** caused
14960 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 by subtriggers s
14970 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 ince those have
14980 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 their own contex
14990 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 t.)^.**.** See a
149a0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
149b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
149c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
149d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
149e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
149f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
14a00 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
14a10 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
14a20 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
14a30 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
14a40 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
14a50 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
14a60 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
14a70 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
14a80 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
14a90 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
14aa0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
14ab0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
14ac0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
14ad0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
14ae0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
14af0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
14b00 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
14b10 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a s Modified.**.**
14b20 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
14b30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
14b40 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 er of row change
14b50 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 s caused by [INS
14b60 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 ERT],.** [UPDATE
14b70 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 ] or [DELETE] st
14b80 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 atements since t
14b90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
14ba0 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 nection] was ope
14bb0 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f ned..** ^(The co
14bc0 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 unt returned by
14bd0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
14be0 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 anges() includes
14bf0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 all changes.**
14c00 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 from all [CREATE
14c10 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
14c20 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 er] contexts and
14c30 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 changes made by
14c40 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
14c50 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 actions]. Howev
14c60 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 er,.** the count
14c70 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
14c80 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 e changes used t
14c90 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 o implement [REP
14ca0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 LACE] constraint
14cb0 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 s,.** do rollbac
14cc0 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 ks or ABORT proc
14cd0 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 essing, or [DROP
14ce0 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 TABLE] processi
14cf0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e ng. The.** coun
14d00 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 t does not inclu
14d10 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 de rows of views
14d20 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 that fire an [I
14d30 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
14d40 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 r],.** though if
14d50 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 the INSTEAD OF
14d60 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 trigger makes ch
14d70 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e anges of its own
14d80 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 , those changes
14d90 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e .** are counted.
14da0 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 )^.** ^The sqlit
14db0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
14dc0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e () function coun
14dd0 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 ts the changes a
14de0 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 s soon as.** the
14df0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
14e00 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f makes them is co
14e10 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 mpleted (when th
14e20 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 e statement hand
14e30 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 le.** is passed
14e40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
14e50 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
14e60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a _finalize()])..*
14e70 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
14e80 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
14e90 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
14ea0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
14eb0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
14ec0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 and the [total_c
14ed0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
14ee0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
14ef0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
14f00 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
14f10 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
14f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14f30 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
14f40 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
14f50 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
14f60 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a hen the value.**
14f70 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 returned is unp
14f80 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
14f90 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
14fa0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
14fb0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
14fc0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
14fd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
14fe0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c F: Interrupt A L
14ff0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 ong-Running Quer
15000 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 y.**.** ^This fu
15010 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e nction causes an
15020 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 y pending databa
15030 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 se operation to
15040 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 abort and.** ret
15050 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 urn at its earli
15060 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e est opportunity.
15070 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
15080 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 typically.** ca
15090 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 lled in response
150a0 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f to a user actio
150b0 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 n such as pressi
150c0 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f ng "Cancel".** o
150d0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 r Ctrl-C where t
150e0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 he user wants a
150f0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 long query opera
15100 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 tion to halt.**
15110 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a immediately..**.
15120 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 ** ^It is safe t
15130 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 o call this rout
15140 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 ine from a threa
15150 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d d different from
15160 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 the.** thread t
15170 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 hat is currently
15180 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 running the dat
15190 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e abase operation.
151a0 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e But it.** is n
151b0 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 ot safe to call
151c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
151d0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f h a [database co
151e0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a nnection] that.*
151f0 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d * is closed or m
15200 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 ight close befor
15210 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
15220 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a upt() returns..*
15230 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 *.** ^If an SQL
15240 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 operation is ver
15250 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 y nearly finishe
15260 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 d at the time wh
15270 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e en.** sqlite3_in
15280 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c terrupt() is cal
15290 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 led, then it mig
152a0 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f ht not have an o
152b0 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f pportunity.** to
152c0 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 be interrupted
152d0 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e and might contin
152e0 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e ue to completion
152f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 ..**.** ^An SQL
15300 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 operation that i
15310 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 s interrupted wi
15320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
15330 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a E_INTERRUPT]..**
15340 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 ^If the interru
15350 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 pted SQL operati
15360 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c on is an INSERT,
15370 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
15380 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e TE.** that is in
15390 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 side an explicit
153a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
153b0 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 en the entire tr
153c0 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c ansaction.** wil
153d0 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b l be rolled back
153e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a automatically..
153f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
15400 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 e3_interrupt(D)
15410 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 call is in effec
15420 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 t until all curr
15430 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a ently running.**
15440 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
15450 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
15460 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c nection] D compl
15470 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 ete. ^Any new S
15480 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
15490 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
154a0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 d after the sqli
154b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
154c0 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 call and before
154d0 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 the .** running
154e0 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 statements reach
154f0 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 es zero are inte
15500 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 rrupted as if th
15510 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 ey had been.** r
15520 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 unning prior to
15530 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
15540 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e rrupt() call. ^
15550 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e New SQL statemen
15560 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
15570 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
15580 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 running stateme
15590 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 nt count reaches
155a0 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 zero are.** not
155b0 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 effected by the
155c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
155d0 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c pt()..** ^A call
155e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 to sqlite3_inte
155f0 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 rrupt(D) that oc
15600 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 curs when there
15610 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a are no running.*
15620 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
15630 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 is a no-op and
15640 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e has no effect on
15650 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
15660 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
15670 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
15680 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
15690 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a ) call returns..
156a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 **.** If the dat
156b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
156c0 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 closes while [s
156d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
156e0 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e ()].** is runnin
156f0 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 g then bad thing
15700 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 s will likely ha
15710 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ppen..*/.SQLITE_
15720 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
15730 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 _interrupt(sqlit
15740 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
15750 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
15760 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 If An SQL State
15770 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 ment Is Complete
15780 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
15790 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c tines are useful
157a0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d during command-
157b0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 line input to de
157c0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a termine if the.*
157d0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 * currently ente
157e0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 red text seems t
157f0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 o form a complet
15800 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
15810 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f or.** if additio
15820 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 nal input is nee
15830 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 ded before sendi
15840 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f ng the text into
15850 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 .** SQLite for p
15860 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 arsing. ^These
15870 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
15880 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 1 if the input s
15890 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 tring.** appears
158a0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 to be a complet
158b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
158c0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 ^A statement i
158d0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a s judged to be.*
158e0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 * complete if it
158f0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d ends with a sem
15900 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 icolon token and
15910 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 is not a prefix
15920 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f of a.** well-fo
15930 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 rmed CREATE TRIG
15940 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 GER statement.
15950 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 ^Semicolons that
15960 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 are embedded wi
15970 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c thin.** string l
15980 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 iterals or quote
15990 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d d identifier nam
159a0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 es or comments a
159b0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 re not.** indepe
159c0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 ndent tokens (th
159d0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 ey are part of t
159e0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 he token in whic
159f0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d h they are.** em
15a00 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 bedded) and thus
15a10 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 do not count as
15a20 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 a statement ter
15a30 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 minator. ^White
15a40 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d space.** and com
15a50 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f ments that follo
15a60 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 w the final semi
15a70 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 colon are ignore
15a80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 d..**.** ^These
15a90 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
15aa0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 0 if the stateme
15ab0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 nt is incomplete
15ac0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f . ^If a.** memo
15ad0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
15ae0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 ils, then SQLITE
15af0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e _NOMEM is return
15b00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ed..**.** ^These
15b10 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 routines do not
15b20 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 parse the SQL s
15b30 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a tatements thus.*
15b40 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 * will not detec
15b50 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 t syntactically
15b60 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a incorrect SQL..*
15b70 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 *.** ^(If SQLite
15b80 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e has not been in
15b90 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 itialized using
15ba0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
15bb0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a ize()] prior .**
15bc0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c to invoking sql
15bd0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
15be0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 ) then sqlite3_i
15bf0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
15c00 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 nvoked.** automa
15c10 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
15c20 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e e3_complete16().
15c30 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 If that initia
15c40 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a lization fails,.
15c50 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
15c60 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
15c70 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
15c80 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a () will be non-z
15c90 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 ero.** regardles
15ca0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
15cb0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 not the input SQ
15cc0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e L is complete.)^
15cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 .**.** The input
15ce0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
15cf0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 plete()] must be
15d00 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
15d10 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 ed.** UTF-8 stri
15d20 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ng..**.** The in
15d30 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
15d40 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 complete16()] mu
15d50 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
15d60 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
15d70 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
15d80 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
15d90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
15da0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
15db0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 e(const char *sq
15dc0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
15dd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c nt sqlite3_compl
15de0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 ete16(const void
15df0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *sql);../*.** C
15e00 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 API3REF: Registe
15e10 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 r A Callback To
15e20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 Handle SQLITE_BU
15e30 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 SY Errors.**.**
15e40 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 ^This routine se
15e50 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 ts a callback fu
15e60 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 nction that migh
15e70 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 t be invoked whe
15e80 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 never.** an atte
15e90 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f mpt is made to o
15ea0 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 pen a database t
15eb0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 able that anothe
15ec0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 r thread.** or p
15ed0 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 rocess has locke
15ee0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
15ef0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
15f00 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 s NULL, then [SQ
15f10 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 LITE_BUSY] or [S
15f20 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
15f30 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 KED].** is retur
15f40 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 ned immediately
15f50 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e upon encounterin
15f60 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 g the lock. ^If
15f70 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
15f80 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c ck.** is not NUL
15f90 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c L, then the call
15fa0 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e back might be in
15fb0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 voked with two a
15fc0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 rguments..**.**
15fd0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
15fe0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 ent to the busy
15ff0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 handler is a cop
16000 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
16010 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ointer which.**
16020 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 is the third arg
16030 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
16040 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e _busy_handler().
16050 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ^The second ar
16060 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
16070 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 busy handler ca
16080 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 llback is the nu
16090 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
160a0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 at the busy hand
160b0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 ler has.** been
160c0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 invoked for this
160d0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 locking event.
160e0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 ^If the.** busy
160f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
16100 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 s 0, then no add
16110 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 itional attempts
16120 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 are made to.**
16130 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 access the datab
16140 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f ase and [SQLITE_
16150 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
16160 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 _IOERR_BLOCKED]
16170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
16180 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
16190 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
161a0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 o, then another
161b0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 attempt.** is ma
161c0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 de to open the d
161d0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 atabase for read
161e0 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c ing and the cycl
161f0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a e repeats..**.**
16200 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 The presence of
16210 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
16220 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 does not guarant
16230 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 ee that it will
16240 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 be invoked.** wh
16250 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b en there is lock
16260 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 contention. ^If
16270 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e SQLite determin
16280 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 es that invoking
16290 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e the busy.** han
162a0 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c dler could resul
162b0 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c t in a deadlock,
162c0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 it will go ahea
162d0 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 d and return [SQ
162e0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 LITE_BUSY].** or
162f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
16300 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 LOCKED] instead
16310 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 of invoking the
16320 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
16330 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e Consider a scen
16340 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 ario where one p
16350 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
16360 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 g a read lock th
16370 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 at.** it is tryi
16380 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ng to promote to
16390 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
163a0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 and.** a second
163b0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
163c0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c ing a reserved l
163d0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 ock that it is t
163e0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d rying.** to prom
163f0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 ote to an exclus
16400 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 ive lock. The f
16410 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e irst process can
16420 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 not proceed.** b
16430 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
16440 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f cked by the seco
16450 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nd and the secon
16460 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 d process cannot
16470 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 .** proceed beca
16480 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
16490 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 d by the first.
164a0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 If both process
164b0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 es.** invoke the
164c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 busy handlers,
164d0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b neither will mak
164e0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 e any progress.
164f0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 Therefore,.** S
16500 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 QLite returns [S
16510 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 QLITE_BUSY] for
16520 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
16530 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 s, hoping that t
16540 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 his.** will indu
16550 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f ce the first pro
16560 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 cess to release
16570 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e its read lock an
16580 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 d allow.** the s
16590 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f econd process to
165a0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 proceed..**.**
165b0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 ^The default bus
165c0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
165d0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b LL..**.** ^The [
165e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 SQLITE_BUSY] err
165f0 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 or is converted
16600 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 to [SQLITE_IOERR
16610 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 _BLOCKED].** whe
16620 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 n SQLite is in t
16630 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c he middle of a l
16640 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e arge transaction
16650 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a where all the.*
16660 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e * changes will n
16670 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 ot fit into the
16680 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e in-memory cache.
16690 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a SQLite will.**
166a0 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 already hold a
166b0 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e RESERVED lock on
166c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
166d0 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 le, but it needs
166e0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 .** to promote t
166f0 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c his lock to EXCL
16700 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 USIVE so that it
16710 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 can spill cache
16720 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 .** pages into t
16730 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
16740 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f without harm to
16750 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 concurrent.** r
16760 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 eaders. ^If it
16770 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f is unable to pro
16780 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 mote the lock, t
16790 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 hen the in-memor
167a0 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 y.** cache will
167b0 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e be left in an in
167c0 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 consistent state
167d0 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f and so the erro
167e0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f r.** code is pro
167f0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 moted from the r
16800 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e elatively benign
16810 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 [SQLITE_BUSY] t
16820 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 o.** the more se
16830 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 vere [SQLITE_IOE
16840 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 RR_BLOCKED]. ^T
16850 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 his error code p
16860 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 romotion.** forc
16870 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 es an automatic
16880 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 rollback of the
16890 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 changes. See th
168a0 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 e.** <a href="/c
168b0 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f vstrac/wiki?p=Co
168c0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e rruptionFollowin
168d0 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 gBusyError">.**
168e0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 CorruptionFollow
168f0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e ingBusyError</a>
16900 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 wiki page for a
16910 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 discussion of w
16920 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d hy.** this is im
16930 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e portant..**.** ^
16940 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 (There can only
16950 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
16960 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 handler defined
16970 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 for each.** [da
16980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16990 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e n]. Setting a n
169a0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 ew busy handler
169b0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 clears any.** pr
169c0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e eviously set han
169d0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 dler.)^ ^Note t
169e0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c hat calling [sql
169f0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
16a00 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 t()].** will als
16a10 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 o set or clear t
16a20 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
16a30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 .**.** The busy
16a40 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 callback should
16a50 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 not take any act
16a60 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 ions which modif
16a70 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 y the.** databas
16a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
16a90 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
16aa0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 sy handler. Any
16ab0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a such actions.**
16ac0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
16ad0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a ined behavior..*
16ae0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e * .** A busy han
16af0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c dler must not cl
16b00 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ose the database
16b10 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
16b20 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 r [prepared stat
16b30 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f ement] that invo
16b40 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
16b50 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f dler..*/.SQLITE_
16b60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
16b70 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c busy_handler(sql
16b80 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f ite3*, int(*)(vo
16b90 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 id*,int), void*)
16ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
16bb0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 F: Set A Busy Ti
16bc0 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 meout.**.** ^Thi
16bd0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 s routine sets a
16be0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 [sqlite3_busy_h
16bf0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 andler | busy ha
16c00 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 ndler] that slee
16c10 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 ps.** for a spec
16c20 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 ified amount of
16c30 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c time when a tabl
16c40 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 e is locked. ^T
16c50 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 he handler.** wi
16c60 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c ll sleep multipl
16c70 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 e times until at
16c80 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c least "ms" mill
16c90 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
16ca0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 ping.** have acc
16cb0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 umulated. ^Afte
16cc0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 r at least "ms"
16cd0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
16ce0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 sleeping,.** the
16cf0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 handler returns
16d00 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 0 which causes
16d10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
16d20 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 to return.** [S
16d30 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
16d40 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
16d50 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 CKED]..**.** ^Ca
16d60 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 lling this routi
16d70 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d ne with an argum
16d80 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 ent less than or
16d90 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a equal to zero.*
16da0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 * turns off all
16db0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a busy handlers..*
16dc0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
16dd0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
16de0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
16df0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a or a particular.
16e00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
16e10 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 nection] any any
16e20 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 given moment.
16e30 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 If another busy
16e40 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 handler.** was d
16e50 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b efined (using [
16e60 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
16e70 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 dler()]) prior t
16e80 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 o calling.** thi
16e90 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 s routine, that
16ea0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
16eb0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e er is cleared.)^
16ec0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
16ed0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
16ee0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
16ef0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
16f00 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
16f10 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
16f20 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
16f30 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ries.**.** This
16f40 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 is a legacy inte
16f50 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 rface that is pr
16f60 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b eserved for back
16f70 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
16f80 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 ity..** Use of t
16f90 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
16fa0 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 not recommended
16fb0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 ..**.** Definiti
16fc0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
16fd0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
16fe0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
16ff0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
17000 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
17010 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
17020 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
17030 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
17040 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
17050 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
17060 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
17070 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
17080 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
17090 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
170a0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
170b0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
170c0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
170d0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
170e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
170f0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
17100 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
17110 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
17120 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
17130 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
17140 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
17150 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
17160 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
17170 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
17180 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
17190 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
171a0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
171b0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
171c0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
171d0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
171e0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
171f0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
17200 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
17210 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
17220 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
17230 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
17240 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
17250 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
17260 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
17270 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
17280 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
17290 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
172a0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
172b0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
172c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
172d0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
172e0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
172f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
17300 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
17310 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
17320 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
17330 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
17340 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
17350 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
17360 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
17370 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
17380 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
17390 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
173a0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
173b0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
173c0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
173d0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
173e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e ]..**.** ^(As an
173f0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
17400 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
17410 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
17420 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
17430 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
17440 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
17450 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
17460 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
17470 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
17480 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
17490 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
174a0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
174b0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
174c0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
174d0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
174e0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
174f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
17500 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
17510 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
17520 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
17530 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
17540 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
17550 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
17560 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
17570 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
17580 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
17590 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
175a0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
175b0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
175c0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
175d0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
175e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
175f0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
17600 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
17610 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
17620 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
17630 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
17640 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
17650 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
17660 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
17670 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
17680 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
17690 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
176a0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
176b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
176c0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
176d0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
176e0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
176f0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
17700 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
17710 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
17720 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
17730 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
17740 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
17750 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
17760 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
17770 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
17780 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
17790 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
177a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
177b0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 nd returns a res
177c0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 ult table to the
177d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 .** pointer give
177e0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 n in its 3rd par
177f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 ameter..**.** Af
17800 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 ter the applicat
17810 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
17820 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 with the result
17830 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 from sqlite3_ge
17840 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 t_table(),.** it
17850 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 must pass the r
17860 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e esult table poin
17870 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
17880 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
17890 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
178a0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
178b0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
178c0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
178d0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
178e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
178f0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
17900 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
17910 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
17920 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
17930 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
17940 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
17950 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
17960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
17970 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
17980 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
17990 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
179a0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
179b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
179c0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
179d0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
179e0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
179f0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
17a00 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
17a10 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
17a20 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
17a30 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
17a40 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
17a50 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
17a60 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
17a70 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
17a80 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
17a90 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
17aa0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
17ab0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
17ac0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
17ad0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
17ae0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
17af0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
17b00 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
17b10 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
17b20 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
17b30 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
17b40 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
17b50 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
17b60 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 errmsg()]..*/.SQ
17b70 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
17b80 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
17b90 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
17ba0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
17bb0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
17bc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
17bd0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
17be0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
17bf0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
17c00 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
17c10 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
17c20 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
17c30 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
17c40 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
17c50 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
17c60 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
17c70 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
17c80 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
17c90 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
17ca0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
17cb0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
17cc0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
17cd0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
17ce0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
17cf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 sqlite3_free_ta
17d00 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c ble(char **resul
17d10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
17d20 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 REF: Formatted S
17d30 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 tring Printing F
17d40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 unctions.**.** T
17d50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
17d60 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 e work-alikes of
17d70 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 the "printf()"
17d80 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 family of functi
17d90 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 ons.** from the
17da0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
17db0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ry..**.** ^The s
17dc0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
17dd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 and sqlite3_vmp
17de0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 rintf() routines
17df0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 write their.**
17e00 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d results into mem
17e10 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
17e20 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
17e30 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 c()]..** The str
17e40 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
17e50 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 these two routi
17e60 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a nes should be.**
17e70 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 released by [sq
17e80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 lite3_free()].
17e90 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 ^Both routines r
17ea0 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 eturn a.** NULL
17eb0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 pointer if [sqli
17ec0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 te3_malloc()] is
17ed0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
17ee0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 ate enough.** me
17ef0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
17f00 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
17f10 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 g..**.** ^(The s
17f20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
17f30 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
17f40 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 ilar to "snprint
17f50 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 f()" from.** the
17f60 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
17f70 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 ary. The result
17f80 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
17f90 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 the.** buffer s
17fa0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 upplied as the s
17fb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
17fc0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 whose size is gi
17fd0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 ven by.** the fi
17fe0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e rst parameter. N
17ff0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 ote that the ord
18000 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 er of the.** fir
18010 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 st two parameter
18020 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 s is reversed fr
18030 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e om snprintf().)^
18040 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 This is an.**
18050 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 historical accid
18060 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 ent that cannot
18070 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 be fixed without
18080 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 breaking.** bac
18090 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
180a0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c lity. ^(Note al
180b0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f so that sqlite3_
180c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 snprintf().** re
180d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
180e0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e to its buffer in
180f0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d stead of the num
18100 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 ber of.** charac
18110 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 ters actually wr
18120 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 itten into the b
18130 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d uffer.)^ We adm
18140 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e it that.** the n
18150 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
18160 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c ers written woul
18170 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 d be a more usef
18180 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c ul return.** val
18190 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 ue but we cannot
181a0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c change the impl
181b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
181c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
181d0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 .** now without
181e0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 breaking compati
181f0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 bility..**.** ^A
18200 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
18210 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
18220 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
18230 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
18240 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
18250 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
18260 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
18270 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 terminated. ^Th
18280 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
18290 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 eter "n" is the
182a0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 total size of th
182b0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 e buffer, includ
182c0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a ing space for.**
182d0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
182e0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f ator. So the lo
182f0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 ngest string tha
18300 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 t can be complet
18310 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 ely.** written w
18320 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 ill be n-1 chara
18330 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 cters..**.** ^Th
18340 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 e sqlite3_vsnpri
18350 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ntf() routine is
18360 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 a varargs versi
18370 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e on of sqlite3_sn
18380 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 printf()..**.**
18390 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
183a0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d ll implement som
183b0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 e additional for
183c0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f matting.** optio
183d0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 ns that are usef
183e0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 ul for construct
183f0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ing SQL statemen
18400 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 ts..** All of th
18410 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 e usual printf()
18420 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
18430 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 ons apply. In a
18440 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a ddition, there.*
18450 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 * is are "%q", "
18460 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 %Q", and "%z" op
18470 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 tions..**.** ^(T
18480 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 he %q option wor
18490 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 ks like %s in th
184a0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 at it substitute
184b0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 s a nul-terminat
184c0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f ed.** string fro
184d0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c m the argument l
184e0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 ist. But %q als
184f0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 o doubles every
18500 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a '\'' character..
18510 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 ** %q is designe
18520 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 d for use inside
18530 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
18540 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e l.)^ By doublin
18550 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 g each '\''.** c
18560 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 haracter it esca
18570 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 pes that charact
18580 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 er and allows it
18590 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 to be inserted
185a0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 into.** the stri
185b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 ng..**.** For ex
185c0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 ample, assume th
185d0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c e string variabl
185e0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 e zText contains
185f0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 text as follows
18600 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
18610 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
18620 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 ar *zText = "It'
18630 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b s a happy day!";
18640 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
18650 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e kquote>.**.** On
18660 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 e can use this t
18670 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 ext in an SQL st
18680 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f atement as follo
18690 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
186a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
186b0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c char *zSQL = sql
186c0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e ite3_mprintf("IN
186d0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 SERT INTO table
186e0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a VALUES('%q')", z
186f0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
18700 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
18710 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
18720 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
18730 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
18740 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
18750 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 Because the %q
18760 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 format string is
18770 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 used, the '\''
18780 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 character in zTe
18790 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 xt.** is escaped
187a0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e and the SQL gen
187b0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c erated is as fol
187c0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
187d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
187e0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 INSERT INTO ta
187f0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 ble1 VALUES('It'
18800 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
18810 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ).** </pre></blo
18820 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
18830 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 his is correct.
18840 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 Had we used %s
18850 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 instead of %q, t
18860 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c he generated SQL
18870 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c .** would have l
18880 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a ooked like this:
18890 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
188a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
188b0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
188c0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 VALUES('It's a h
188d0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 appy day!');.**
188e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
188f0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 te>.**.** This s
18900 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 econd example is
18910 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 an SQL syntax e
18920 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 rror. As a gene
18930 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f ral rule you sho
18940 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 uld.** always us
18950 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 e %q instead of
18960 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e %s when insertin
18970 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 g text into a st
18980 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a ring literal..**
18990 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 .** ^(The %Q opt
189a0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 ion works like %
189b0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f q except it also
189c0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f adds single quo
189d0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 tes around.** th
189e0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 e outside of the
189f0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 total string.
18a00 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 Additionally, if
18a10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
18a20 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e n the.** argumen
18a30 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c t list is a NULL
18a40 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 pointer, %Q sub
18a50 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 stitutes the tex
18a60 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 t "NULL" (withou
18a70 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 t.** single quot
18a80 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 es).)^ So, for
18a90 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 example, one cou
18aa0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ld say:.**.** <b
18ab0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
18ac0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d ** char *zSQL =
18ad0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
18ae0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 ("INSERT INTO ta
18af0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c ble VALUES(%Q)",
18b00 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
18b10 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
18b20 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
18b30 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
18b40 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
18b50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
18b60 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 ** The code abov
18b70 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 e will render a
18b80 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 correct SQL stat
18b90 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 ement in the zSQ
18ba0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 L.** variable ev
18bb0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 en if the zText
18bc0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 variable is a NU
18bd0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
18be0 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 * ^(The "%z" for
18bf0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 matting option w
18c00 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 orks like "%s" b
18c10 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 ut with the.** a
18c20 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 ddition that aft
18c30 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 er the string ha
18c40 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 s been read and
18c50 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 copied into.** t
18c60 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 he result, [sqli
18c70 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 te3_free()] is c
18c80 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 alled on the inp
18c90 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a ut string.)^.*/.
18ca0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
18cb0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 *sqlite3_mprintf
18cc0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
18cd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 );.SQLITE_API ch
18ce0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 ar *sqlite3_vmpr
18cf0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a intf(const char*
18d00 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 , va_list);.SQLI
18d10 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c TE_API char *sql
18d20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e ite3_snprintf(in
18d30 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t,char*,const ch
18d40 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 ar*, ...);.SQLIT
18d50 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 E_API char *sqli
18d60 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e te3_vsnprintf(in
18d70 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t,char*,const ch
18d80 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a ar*, va_list);..
18d90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18da0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
18db0 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a n Subsystem.**.*
18dc0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * The SQLite cor
18dd0 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 e uses these thr
18de0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 ee routines for
18df0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a all of its own.*
18e00 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 * internal memor
18e10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
18e20 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 ds. "Core" in th
18e30 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 e previous sente
18e40 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 nce.** does not
18e50 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e include operatin
18e60 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 g-system specifi
18e70 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 c VFS implementa
18e80 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 tion. The.** Wi
18e90 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e ndows VFS uses n
18ea0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 ative malloc() a
18eb0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f nd free() for so
18ec0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a me operations..*
18ed0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
18ee0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 3_malloc() routi
18ef0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ne returns a poi
18f00 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a nter to a block.
18f10 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 ** of memory at
18f20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e least N bytes in
18f30 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e length, where N
18f40 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 is the paramete
18f50 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 r..** ^If sqlite
18f60 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 3_malloc() is un
18f70 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 able to obtain s
18f80 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a ufficient free.*
18f90 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 * memory, it ret
18fa0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
18fb0 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 ter. ^If the pa
18fc0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 rameter N to.**
18fd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
18fe0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 is zero or nega
18ff0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 tive then sqlite
19000 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 3_malloc() retur
19010 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 ns.** a NULL poi
19020 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c nter..**.** ^Cal
19030 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 ling sqlite3_fre
19040 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 e() with a point
19050 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 er previously re
19060 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
19070 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
19080 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
19090 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 () releases that
190a0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 memory so.** th
190b0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 at it might be r
190c0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c eused. ^The sql
190d0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
190e0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
190f0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
19100 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
19110 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
19120 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
19130 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
19140 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
19150 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
19160 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
19170 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
19180 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
19190 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
191a0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
191b0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
191c0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
191d0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
191e0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
191f0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
19200 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
19210 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
19220 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
19230 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
19240 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
19250 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
19260 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
19270 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
19280 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
19290 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
192a0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
192b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
192c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 **.** ^(The sqli
192d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e te3_realloc() in
192e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
192f0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 to resize a.**
19300 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c prior memory all
19310 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 ocation to be at
19320 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 least N bytes,
19330 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a where N is the.*
19340 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
19350 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 er. The memory
19360 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 allocation to be
19370 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 resized is the
19380 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
19390 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 er.)^ ^ If the f
193a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
193b0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
193c0 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c c().** is a NULL
193d0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 pointer then it
193e0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 s behavior is id
193f0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 entical to calli
19400 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ng.** sqlite3_ma
19410 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 lloc(N) where N
19420 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 is the second pa
19430 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
19440 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
19450 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 ^If the second
19460 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
19470 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 ite3_realloc() i
19480 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 s zero or.** neg
19490 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 ative then the b
194a0 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 ehavior is exact
194b0 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 ly the same as c
194c0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
194d0 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 3_free(P) where
194e0 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 P is the first p
194f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
19500 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
19510 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c * ^sqlite3_reall
19520 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 oc() returns a p
19530 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
19540 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
19550 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 of at least N b
19560 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 ytes in size or
19570 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 NULL if sufficie
19580 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 nt memory is una
19590 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 vailable..** ^If
195a0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f M is the size o
195b0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f f the prior allo
195c0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e cation, then min
195d0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f (N,M) bytes.** o
195e0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f f the prior allo
195f0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 cation are copie
19600 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e d into the begin
19610 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 ning of buffer r
19620 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
19630 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
19640 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c and the prior al
19650 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 location is free
19660 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 d..** ^If sqlite
19670 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 3_realloc() retu
19680 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 rns NULL, then t
19690 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
196a0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 ion.** is not fr
196b0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
196c0 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 memory returned
196d0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
196e0 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f c() and sqlite3_
196f0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 realloc().** is
19700 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 always aligned t
19710 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 o at least an 8
19720 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f byte boundary, o
19730 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 r to a.** 4 byte
19740 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 boundary if the
19750 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f [SQLITE_4_BYTE_
19760 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 ALIGNED_MALLOC]
19770 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 compile-time.**
19780 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a option is used..
19790 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 **.** In SQLite
197a0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e version 3.5.0 an
197b0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 d 3.5.1, it was
197c0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 possible to defi
197d0 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 ne.** the SQLITE
197e0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c _OMIT_MEMORY_ALL
197f0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f OCATION which wo
19800 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 uld cause the bu
19810 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d ilt-in.** implem
19820 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 entation of thes
19830 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 e routines to be
19840 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 omitted. That
19850 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 capability.** is
19860 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 no longer provi
19870 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 ded. Only built
19880 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
19890 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 ators can be use
198a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e d..**.** The Win
198b0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 dows OS interfac
198c0 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a e layer calls.**
198d0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c the system mall
198e0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
198f0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f directly when co
19900 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 nverting.** file
19910 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 names between th
19920 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 e UTF-8 encoding
19930 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a used by SQLite.
19940 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 ** and whatever
19950 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e filename encodin
19960 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 g is used by the
19970 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 particular Wind
19980 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 ows.** installat
19990 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c ion. Memory all
199a0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 ocation errors a
199b0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 re detected, but
199c0 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 .** they are rep
199d0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 orted back as [S
199e0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
199f0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f or.** [SQLITE_IO
19a00 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e ERR] rather than
19a10 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
19a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 .**.** The point
19a30 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 er arguments to
19a40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
19a50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
19a60 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 alloc()].** must
19a70 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 be either NULL
19a80 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 or else pointers
19a90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
19aa0 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 prior.** invoca
19ab0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
19ac0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
19ad0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
19ae0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e ] that have.** n
19af0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 ot yet been rele
19b00 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ased..**.** The
19b10 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
19b20 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 not read or wri
19b30 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a te any part of.*
19b40 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d * a block of mem
19b50 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 ory after it has
19b60 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 been released u
19b70 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
19b80 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c _free()] or [sql
19b90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e ite3_realloc()].
19ba0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
19bb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c oid *sqlite3_mal
19bc0 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 loc(int);.SQLITE
19bd0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
19be0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a e3_realloc(void*
19bf0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
19c00 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
19c10 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a free(void*);../*
19c20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
19c30 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
19c40 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 tatistics.**.**
19c50 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 SQLite provides
19c60 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 these two interf
19c70 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 aces for reporti
19c80 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 ng on the status
19c90 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
19ca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
19cb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c sqlite3_free()],
19cc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
19cd0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 alloc()].** rout
19ce0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d ines, which form
19cf0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 the built-in me
19d00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
19d10 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a subsystem..**.**
19d20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
19d30 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f emory_used()] ro
19d40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
19d50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
19d60 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 s.** of memory c
19d70 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e urrently outstan
19d80 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 ding (malloced b
19d90 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a ut not freed)..*
19da0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
19db0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
19dc0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
19dd0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
19de0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c ** value of [sql
19df0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
19e00 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
19e10 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
19e20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e was last reset.
19e30 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 ^The values re
19e40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
19e50 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
19e60 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
19e70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
19e80 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
19e90 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 y overhead.** ad
19ea0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
19eb0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
19ec0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
19ed0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 malloc()],.** bu
19ee0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 t not overhead a
19ef0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 dded by the any
19f00 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 underlying syste
19f10 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 m library.** rou
19f20 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
19f30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
19f40 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y call..**.** ^T
19f50 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 he memory high-w
19f60 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
19f70 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e et to the curren
19f80 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 t value of.** [s
19f90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
19fa0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
19fb0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
19fc0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
19fd0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
19fe0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 er()] is true.
19ff0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
1a000 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 ned.** by [sqlit
1a010 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1a020 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 ter(1)] is the h
1a030 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
1a040 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 * prior to the r
1a050 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f eset..*/.SQLITE_
1a060 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
1a070 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
1a080 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c _used(void);.SQL
1a090 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
1a0a0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
1a0b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 mory_highwater(i
1a0c0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a nt resetFlag);..
1a0d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1a0e0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 Pseudo-Random Nu
1a0f0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a mber Generator.*
1a100 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 *.** SQLite cont
1a110 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c ains a high-qual
1a120 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f ity pseudo-rando
1a130 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 m number generat
1a140 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 or (PRNG) used t
1a150 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 o.** select rand
1a160 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 om [ROWID | ROWI
1a170 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 Ds] when inserti
1a180 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 ng new records i
1a190 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 nto a table that
1a1a0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 .** already uses
1a1b0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 the largest pos
1a1c0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 sible [ROWID].
1a1d0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f The PRNG is also
1a1e0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 used for.** the
1a1f0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d build-in random
1a200 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f () and randomblo
1a210 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e b() SQL function
1a220 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 s. This interfa
1a230 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 ce allows.** app
1a240 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 lications to acc
1a250 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e ess the same PRN
1a260 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 G for other purp
1a270 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 oses..**.** ^A c
1a280 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 all to this rout
1a290 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 ine stores N byt
1a2a0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
1a2b0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a into buffer P..
1a2c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
1a2d0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 time this routi
1a2e0 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 ne is invoked (e
1a2f0 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 ither internally
1a300 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 or by.** the ap
1a310 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 plication) the P
1a320 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 RNG is seeded us
1a330 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f ing randomness o
1a340 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
1a350 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 the xRandomness
1a360 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 method of the de
1a370 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
1a380 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e fs] object..** ^
1a390 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e On all subsequen
1a3a0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 t invocations, t
1a3b0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d he pseudo-random
1a3c0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 ness is generate
1a3d0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 d.** internally
1a3e0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f and without reco
1a3f0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c urse to the [sql
1a400 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f ite3_vfs] xRando
1a410 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e mness.** method.
1a420 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
1a430 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 oid sqlite3_rand
1a440 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f omness(int N, vo
1a450 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id *P);../*.** C
1a460 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 API3REF: Compile
1a470 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 -Time Authorizat
1a480 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
1a490 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
1a4a0 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 e registers an a
1a4b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1a4c0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ck with a partic
1a4d0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
1a4e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 e connection], s
1a4f0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 upplied in the f
1a500 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
1a510 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 * ^The authorize
1a520 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
1a530 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
1a540 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e tements are bein
1a550 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 g compiled.** by
1a560 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1a570 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
1a580 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 ants [sqlite3_pr
1a590 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 epare_v2()],.**
1a5a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1a5b0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 16()] and [sqlit
1a5c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1a5d0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 )]. ^At various
1a5e0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e .** points durin
1a5f0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f g the compilatio
1a600 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f n process, as lo
1a610 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 gic is being cre
1a620 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f ated.** to perfo
1a630 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f rm various actio
1a640 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a ns, the authoriz
1a650 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
1a660 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 nvoked to.** see
1a670 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e if those action
1a680 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 s are allowed.
1a690 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ^The authorizer
1a6a0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a callback should.
1a6b0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
1a6c0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 E_OK] to allow t
1a6d0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 he action, [SQLI
1a6e0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 TE_IGNORE] to di
1a6f0 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 sallow the.** sp
1a700 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 ecific action bu
1a710 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 t allow the SQL
1a720 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e statement to con
1a730 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 tinue to be.** c
1a740 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c ompiled, or [SQL
1a750 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 ITE_DENY] to cau
1a760 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 se the entire SQ
1a770 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 L statement to b
1a780 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 e.** rejected wi
1a790 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 th an error. ^I
1a7a0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 f the authorizer
1a7b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1a7c0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f s.** any value o
1a7d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1a7e0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 E_IGNORE], [SQLI
1a7f0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 TE_OK], or [SQLI
1a800 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e TE_DENY].** then
1a810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
1a820 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
1a830 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
1a840 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a hat triggered.**
1a850 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1a860 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
1a870 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
1a880 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
1a890 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1a8a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
1a8b0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 at means the ope
1a8c0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 ration.** reques
1a8d0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 ted is ok. ^Whe
1a8e0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
1a8f0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 eturns [SQLITE_D
1a900 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 ENY], the.** [sq
1a910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1a920 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
1a930 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
1a940 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 gered the.** aut
1a950 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
1a960 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
1a970 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 message explaini
1a980 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 ng that.** acces
1a990 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a s is denied. .**
1a9a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
1a9b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1a9c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1a9d0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
1a9e0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
1a9f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
1aa00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1aa10 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 rizer() interfac
1aa20 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 e. ^The second p
1aa30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
1aa40 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
1aa50 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 n integer [SQLIT
1aa60 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 E_COPY | action
1aa70 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 code] that speci
1aa80 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 fies.** the part
1aa90 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f icular action to
1aaa0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 be authorized.
1aab0 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 ^The third throu
1aac0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 gh sixth paramet
1aad0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ers.** to the ca
1aae0 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d llback are zero-
1aaf0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
1ab00 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 gs that contain
1ab10 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 additional.** de
1ab20 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 tails about the
1ab30 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
1ab40 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e horized..**.** ^
1ab50 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
1ab60 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 de is [SQLITE_RE
1ab70 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 AD].** and the c
1ab80 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1ab90 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1aba0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 then the.** [pre
1abb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1abc0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
1abd0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 nstructed to sub
1abe0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c stitute.** a NUL
1abf0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 L value in place
1ac00 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f of the table co
1ac10 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 lumn that would
1ac20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 have.** been rea
1ac30 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
1ac40 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
1ac50 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 ed. The [SQLITE
1ac60 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 _IGNORE].** retu
1ac70 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 rn can be used t
1ac80 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 o deny an untrus
1ac90 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 ted user access
1aca0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a to individual.**
1acb0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 columns of a ta
1acc0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ble..** ^If the
1acd0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
1ace0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 SQLITE_DELETE] a
1acf0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 nd the callback
1ad00 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 returns.** [SQLI
1ad10 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
1ad20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 the [DELETE] ope
1ad30 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 ration proceeds
1ad40 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e but the.** [trun
1ad50 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f cate optimizatio
1ad60 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 n] is disabled a
1ad70 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 nd all rows are
1ad80 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 deleted individu
1ad90 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 ally..**.** An a
1ada0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 uthorizer is use
1adb0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f d when [sqlite3_
1adc0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
1add0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ing].** SQL stat
1ade0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 ements from an u
1adf0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c ntrusted source,
1ae00 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 to ensure that
1ae10 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1ae20 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 ts.** do not try
1ae30 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 to access data
1ae40 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c they are not all
1ae50 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 owed to see, or
1ae60 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 that they do not
1ae70 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 .** try to execu
1ae80 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 te malicious sta
1ae90 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d tements that dam
1aea0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 age the database
1aeb0 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c . For.** exampl
1aec0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
1aed0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 n may allow a us
1aee0 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 er to enter arbi
1aef0 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 trary.** SQL que
1af00 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 ries for evaluat
1af10 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 ion by a databas
1af20 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c e. But the appl
1af30 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 ication does.**
1af40 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 not want the use
1af50 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 r to be able to
1af60 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 make arbitrary c
1af70 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a hanges to the.**
1af80 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 database. An a
1af90 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 uthorizer could
1afa0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 then be put in p
1afb0 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a lace while the.*
1afc0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 * user-entered S
1afd0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c QL is being [sql
1afe0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
1aff0 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a repared] that.**
1b000 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 disallows every
1b010 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 thing except [SE
1b020 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 LECT] statements
1b030 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ..**.** Applicat
1b040 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 ions that need t
1b050 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 o process SQL fr
1b060 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 om untrusted sou
1b070 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c rces.** might al
1b080 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 so consider lowe
1b090 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 ring resource li
1b0a0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 mits using [sqli
1b0b0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
1b0c0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 and limiting dat
1b0d0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 abase size using
1b0e0 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 the [max_page_c
1b0f0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a ount] [PRAGMA].*
1b100 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f * in addition to
1b110 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 using an author
1b120 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e izer..**.** ^(On
1b130 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 ly a single auth
1b140 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e orizer can be in
1b150 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 place on a data
1b160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1b170 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 ** at a time. E
1b180 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
1b190 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1b1a0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 er overrides the
1b1b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c .** previous cal
1b1c0 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 l.)^ ^Disable t
1b1d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 he authorizer by
1b1e0 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 installing a NU
1b1f0 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 LL callback..**
1b200 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 The authorizer i
1b210 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 s disabled by de
1b220 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fault..**.** The
1b230 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1b240 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f back must not do
1b250 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
1b260 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
1b270 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1b280 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
1b290 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ed the authorize
1b2a0 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e r callback..** N
1b2b0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
1b2c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1b2d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
1b2e0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
1b2f0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
1b300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
1b310 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
1b320 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
1b330 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
1b340 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 .** ^When [sqlit
1b350 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1b360 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 is used to prep
1b370 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c are a statement,
1b380 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
1b390 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 t might be re-pr
1b3a0 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 epared during [s
1b3b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 qlite3_step()] d
1b3c0 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 ue to a .** sche
1b3d0 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 ma change. Henc
1b3e0 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 e, the applicati
1b3f0 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 on should ensure
1b400 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 that the.** cor
1b410 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 rect authorizer
1b420 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 callback remains
1b430 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 in place during
1b440 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
1b450 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f ep()]..**.** ^No
1b460 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 te that the auth
1b470 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1b480 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 is invoked only
1b490 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 during.** [sqlit
1b4a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
1b4b0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 its variants.
1b4c0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 Authorization is
1b4d0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 not.** performe
1b4e0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 d during stateme
1b4f0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e nt evaluation in
1b500 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1b510 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 ], unless.** as
1b520 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 stated in the pr
1b530 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
1b540 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 , sqlite3_step()
1b550 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 invokes.** sqli
1b560 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1b570 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 to reprepare a
1b580 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 statement after
1b590 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e a schema change.
1b5a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
1b5b0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 nt sqlite3_set_a
1b5c0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c uthorizer(. sql
1b5d0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 ite3*,. int (*x
1b5e0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c Auth)(void*,int,
1b5f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
1b600 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1b610 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 ar*,const char*)
1b620 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 ,. void *pUserD
1b630 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ata.);../*.** CA
1b640 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
1b650 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a er Return Codes.
1b660 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
1b670 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1b680 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 r | authorizer c
1b690 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1b6a0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e ] must.** return
1b6b0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
1b6c0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 OK] or one of th
1b6d0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 ese two constant
1b6e0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f s in order.** to
1b6f0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 signal SQLite w
1b700 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
1b710 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d e action is perm
1b720 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a itted. See the.
1b730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f ** [sqlite3_set_
1b740 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
1b750 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 horizer document
1b760 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 ation] for addit
1b770 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
1b780 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 tion..**.** Note
1b790 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e that SQLITE_IGN
1b7a0 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 ORE is also used
1b7b0 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f as a [SQLITE_RO
1b7c0 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 LLBACK | return
1b7d0 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 code].** from th
1b7e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f e [sqlite3_vtab_
1b7f0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 on_conflict()] i
1b800 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 nterface..*/.#de
1b810 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 fine SQLITE_DENY
1b820 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 1 /* Abort
1b830 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1b840 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 t with an error
1b850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b860 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 E_IGNORE 2 /*
1b870 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 Don't allow acce
1b880 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 ss, but don't ge
1b890 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 nerate an error
1b8a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
1b8b0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 EF: Authorizer A
1b8c0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a ction Codes.**.*
1b8d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
1b8e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
1b8f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
1b900 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
1b910 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 function.** that
1b920 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 is invoked to a
1b930 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e uthorize certain
1b940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
1b950 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 ctions. The.**
1b960 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1b970 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1b980 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 is an integer c
1b990 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 ode that specifi
1b9a0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f es.** what actio
1b9b0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f n is being autho
1b9c0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 rized. These ar
1b9d0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 e the integer ac
1b9e0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a tion codes that.
1b9f0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
1ba00 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 r callback may b
1ba10 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 e passed..**.**
1ba20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 These action cod
1ba30 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 e values signify
1ba40 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 what kind of op
1ba50 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 eration is to be
1ba60 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 .** authorized.
1ba70 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 The 3rd and 4th
1ba80 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
1ba90 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e he authorization
1baa0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
1bab0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 ction will be pa
1bac0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
1bad0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
1bae0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ich of these.**
1baf0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 codes is used as
1bb00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1bb10 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 meter. ^(The 5t
1bb20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
1bb30 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
1bb40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
1bb50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
1bb60 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 abase ("main", "
1bb70 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 temp",.** etc.)
1bb80 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e if applicable.)^
1bb90 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d ^The 6th param
1bba0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
1bbb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a orizer callback.
1bbc0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
1bbd0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 f the inner-most
1bbe0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 trigger or view
1bbf0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 that is respons
1bc00 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ible for.** the
1bc10 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f access attempt o
1bc20 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 r NULL if this a
1bc30 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 ccess attempt is
1bc40 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a directly from.*
1bc50 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 * top-level SQL
1bc60 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a code..*/./******
1bc70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1bc80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1bc90 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a ***** 3rd ******
1bca0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a ****** 4th *****
1bcb0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 ******/.#define
1bcc0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e SQLITE_CREATE_IN
1bcd0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 DEX 1
1bce0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1bcf0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1bd00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1bd10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 QLITE_CREATE_TAB
1bd20 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 LE 2
1bd30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1bd40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1bd50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1bd60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
1bd70 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f _INDEX 3 /
1bd80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
1bd90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1bda0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1bdb0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
1bdc0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a TABLE 4 /*
1bdd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1bde0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1bdf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1be00 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
1be10 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 RIGGER 5 /*
1be20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
1be30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1be40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1be50 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 E_CREATE_TEMP_VI
1be60 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 EW 6 /* V
1be70 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
1be80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1be90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1bea0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 _CREATE_TRIGGER
1beb0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 7 /* Tr
1bec0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
1bed0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1bee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1bef0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 CREATE_VIEW
1bf00 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 8 /* Vie
1bf10 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
1bf20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1bf30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1bf40 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
1bf50 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 9 /* Tabl
1bf60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1bf70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1bf80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1bf90 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 OP_INDEX
1bfa0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 10 /* Index
1bfb0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
1bfc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1bfd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1bfe0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 P_TABLE
1bff0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 11 /* Table
1c000 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1c010 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1c020 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1c030 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
1c040 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 12 /* Index N
1c050 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
1c060 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1c070 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1c080 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 TEMP_TABLE
1c090 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 13 /* Table Na
1c0a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1c0b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1c0c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1c0d0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 EMP_TRIGGER 1
1c0e0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 4 /* Trigger N
1c0f0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
1c100 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1c110 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
1c120 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 MP_VIEW 15
1c130 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
1c140 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1c150 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1c160 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 SQLITE_DROP_TRI
1c170 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 GGER 16
1c180 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
1c190 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
1c1a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1c1b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 SQLITE_DROP_VIEW
1c1c0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 17
1c1d0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
1c1e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1c1f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1c200 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 QLITE_INSERT
1c210 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 18
1c220 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1c230 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1c240 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1c250 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 LITE_PRAGMA
1c260 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 19 /
1c270 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 * Pragma Name
1c280 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 1st arg or NUL
1c290 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c L */.#define SQL
1c2a0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 ITE_READ
1c2b0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 /*
1c2c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1c2d0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
1c2e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1c2f0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 TE_SELECT
1c300 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 21 /*
1c310 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1c320 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1c330 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1c340 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 E_TRANSACTION
1c350 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 22 /* O
1c360 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e peration N
1c370 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1c380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1c390 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 _UPDATE
1c3a0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 23 /* Ta
1c3b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
1c3c0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
1c3d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1c3e0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 ATTACH
1c3f0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 24 /* Fil
1c400 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c ename NUL
1c410 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1c420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1c430 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 ETACH
1c440 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 25 /* Data
1c450 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c base Name NULL
1c460 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1c470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c define SQLITE_AL
1c480 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 TER_TABLE
1c490 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 26 /* Datab
1c4a0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 ase Name Table
1c4b0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1c4c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 efine SQLITE_REI
1c4d0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 NDEX
1c4e0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 27 /* Index
1c4f0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1c500 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1c510 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c fine SQLITE_ANAL
1c520 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 YZE
1c530 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 28 /* Table N
1c540 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1c550 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1c560 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1c570 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 E_VTABLE
1c580 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 29 /* Table Na
1c590 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
1c5a0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
1c5b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
1c5c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 TABLE 3
1c5d0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
1c5e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
1c5f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
1c600 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f e SQLITE_FUNCTIO
1c610 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 N 31
1c620 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
1c630 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e Function N
1c640 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 ame */.#define
1c650 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e SQLITE_SAVEPOIN
1c660 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 T 32
1c670 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
1c680 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e Savepoint N
1c690 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ame */.#define
1c6a0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 SQLITE_COPY
1c6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 0
1c6c0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 /* No longer us
1c6d0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ed */../*.** CAP
1c6e0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 I3REF: Tracing A
1c6f0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e nd Profiling Fun
1c700 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
1c710 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 se routines regi
1c720 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
1c730 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e nctions that can
1c740 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 be used for.**
1c750 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 tracing and prof
1c760 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 iling the execut
1c770 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ion of SQL state
1c780 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
1c790 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
1c7a0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
1c7b0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
1c7c0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
1c7d0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
1c7e0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
1c7f0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
1c800 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
1c810 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 step()]..** ^The
1c820 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
1c830 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1c840 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d oked with a UTF-
1c850 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 8 rendering of t
1c860 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d he.** SQL statem
1c870 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 ent text as the
1c880 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 statement first
1c890 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 begins executing
1c8a0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 ..** ^(Additiona
1c8b0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 l sqlite3_trace(
1c8c0 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 ) callbacks migh
1c8d0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 t occur.** as ea
1c8e0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
1c8f0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
1c900 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
1c910 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
1c920 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
1c930 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
1c940 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
1c950 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a he trigger.)^.**
1c960 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
1c970 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
1c980 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
1c990 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
1c9a0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
1c9b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
1c9c0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 inishes. ^The p
1c9d0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
1c9e0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
1c9f0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
1ca00 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
1ca10 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
1ca20 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
1ca30 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
1ca40 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
1ca50 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 run. ^The prof
1ca60 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ile callback.**
1ca70 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 time is in units
1ca80 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c of nanoseconds,
1ca90 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 however the cur
1caa0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
1cab0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 ion.** is only c
1cac0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 apable of millis
1cad0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e econd resolution
1cae0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 so the six leas
1caf0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a t significant.**
1cb00 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 digits in the t
1cb10 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c ime are meaningl
1cb20 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 ess. Future ver
1cb30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a sions of SQLite.
1cb40 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 ** might provide
1cb50 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 greater resolut
1cb60 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 ion on the profi
1cb70 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 ler callback. T
1cb80 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 he.** sqlite3_pr
1cb90 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e ofile() function
1cba0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 is considered e
1cbb0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
1cbc0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f is.** subject to
1cbd0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 change in futur
1cbe0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
1cbf0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
1cc00 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
1cc10 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 3_trace(sqlite3*
1cc20 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 , void(*xTrace)(
1cc30 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 void*,const char
1cc40 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 *), void*);.SQLI
1cc50 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 TE_API SQLITE_EX
1cc60 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 PERIMENTAL void
1cc70 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 *sqlite3_profile
1cc80 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f (sqlite3*,. vo
1cc90 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f id(*xProfile)(vo
1cca0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c id*,const char*,
1ccb0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c sqlite3_uint64),
1ccc0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
1ccd0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 CAPI3REF: Query
1cce0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 Progress Callbac
1ccf0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ks.**.** ^The sq
1cd00 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
1cd10 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 andler(D,N,X,P)
1cd20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 interface causes
1cd30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a the callback.**
1cd40 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 function X to b
1cd50 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 e invoked period
1cd60 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f ically during lo
1cd70 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 ng running calls
1cd80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
1cd90 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 exec()], [sqlite
1cda0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 3_step()] and [s
1cdb0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1cdc0 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 ()] for.** datab
1cdd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 ase connection D
1cde0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 . An example us
1cdf0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e e for this.** in
1ce00 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 terface is to ke
1ce10 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 ep a GUI updated
1ce20 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 during a large
1ce30 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 query..**.** ^Th
1ce40 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 e parameter P is
1ce50 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
1ce60 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 as the only para
1ce70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a meter to the .**
1ce80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1ce90 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 on X. ^The para
1cea0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e meter N is the n
1ceb0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 umber of .** [vi
1cec0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e rtual machine in
1ced0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 structions] that
1cee0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 are evaluated b
1cef0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 etween successiv
1cf00 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 e.** invocations
1cf10 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b of the callback
1cf20 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 X..**.** ^Only
1cf30 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 a single progres
1cf40 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 s handler may be
1cf50 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 defined at one
1cf60 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 time per.** [dat
1cf70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1cf80 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 ]; setting a new
1cf90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
1cfa0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a r cancels the.**
1cfb0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 old one. ^Sett
1cfc0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 ing parameter X
1cfd0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 to NULL disables
1cfe0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
1cff0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 ndler..** ^The p
1d000 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
1d010 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 is also disabled
1d020 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f by setting N to
1d030 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a a value less.**
1d040 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e than 1..**.** ^
1d050 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 If the progress
1d060 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1d070 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f non-zero, the o
1d080 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 peration is.** i
1d090 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 nterrupted. Thi
1d0a0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 s feature can be
1d0b0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
1d0c0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 nt a.** "Cancel"
1d0d0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 button on a GUI
1d0e0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 progress dialog
1d0f0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 box..**.** The
1d100 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
1d110 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e callback must n
1d120 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
1d130 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
1d140 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
1d150 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
1d160 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 invoked the prog
1d170 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a ress handler..**
1d180 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
1d190 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1d1a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
1d1b0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
1d1c0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
1d1d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
1d1e0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
1d1f0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
1d200 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
1d210 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 **.*/.SQLITE_API
1d220 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 void sqlite3_pr
1d230 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 ogress_handler(s
1d240 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e qlite3*, int, in
1d250 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
1d260 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1d270 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 3REF: Opening A
1d280 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e New Database Con
1d290 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 nection.**.** ^T
1d2a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 hese routines op
1d2b0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 en an SQLite dat
1d2c0 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 abase file as sp
1d2d0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a ecified by the .
1d2e0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 ** filename argu
1d2f0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e ment. ^The filen
1d300 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
1d310 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
1d320 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 TF-8 for.** sqli
1d330 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
1d340 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1d350 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 and as UTF-16 i
1d360 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
1d370 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 e.** order for s
1d380 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
1d390 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 ^(A [database c
1d3a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
1d3b0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 e is usually.**
1d3c0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 returned in *ppD
1d3d0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 b, even if an er
1d3e0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 ror occurs. The
1d3f0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 only exception
1d400 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 is that.** if SQ
1d410 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
1d420 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
1d430 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 y to hold the [s
1d440 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a qlite3] object,.
1d450 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 ** a NULL will b
1d460 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a e written into *
1d470 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 ppDb instead of
1d480 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
1d490 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 [sqlite3].** ob
1d4a0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 ject.)^ ^(If the
1d4b0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1d4c0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
1d4d0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
1d4e0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
1d4f0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
1d500 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
1d510 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
1d520 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 s returned.)^ ^T
1d530 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
1d540 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c rrmsg()] or [sql
1d550 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
1d560 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 routines can be
1d570 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a used to obtain.
1d580 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 ** an English la
1d590 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 nguage descripti
1d5a0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 on of the error
1d5b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c following a fail
1d5c0 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ure of any.** of
1d5d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 the sqlite3_ope
1d5e0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a n() routines..**
1d5f0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
1d600 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 encoding for th
1d610 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
1d620 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 be UTF-8 if.** s
1d630 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
1d640 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1d650 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 () is called and
1d660 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 .** UTF-16 in th
1d670 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
1d680 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f der if sqlite3_o
1d690 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e pen16() is used.
1d6a0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f .**.** Whether o
1d6b0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f r not an error o
1d6c0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 ccurs when it is
1d6d0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 opened, resourc
1d6e0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 es.** associated
1d6f0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
1d700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1d710 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
1d720 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 released by.**
1d730 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
1d740 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
1d750 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
1d760 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a nger required..*
1d770 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1d780 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 _open_v2() inter
1d790 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 face works like
1d7a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
1d7b0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
1d7c0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 accepts two add
1d7d0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
1d7e0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
1d7f0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 l control.** ove
1d800 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 r the new databa
1d810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
1d820 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 ^(The flags para
1d830 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 meter to.** sqli
1d840 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 te3_open_v2() ca
1d850 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a n take one of.**
1d860 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
1d870 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 hree values, opt
1d880 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
1d890 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 with the .** [S
1d8a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
1d8b0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 EX], [SQLITE_OPE
1d8c0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 N_FULLMUTEX], [S
1d8d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
1d8e0 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c DCACHE],.** [SQL
1d8f0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
1d900 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b CACHE], and/or [
1d910 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
1d920 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 flags:)^.**.**
1d930 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 <dl>.** ^(<dt>[S
1d940 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
1d950 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NLY]</dt>.** <dd
1d960 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
1d970 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d opened in read-
1d980 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 only mode. If t
1d990 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
1d9a0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 not.** already
1d9b0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
1d9c0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
1d9d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
1d9e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
1d9f0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 DWRITE]</dt>.**
1da00 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
1da10 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
1da20 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
1da30 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 ng if possible,
1da40 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e or reading.** on
1da50 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 ly if the file i
1da60 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 s write protecte
1da70 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 d by the operati
1da80 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 ng system. In e
1da90 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 ither.** case th
1daa0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 e database must
1dab0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f already exist, o
1dac0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
1dad0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
1dae0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
1daf0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
1db00 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
1db10 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
1db20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1db30 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1db40 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
1db50 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 and writing, and
1db60 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a is created if.*
1db70 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c * it does not al
1db80 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 ready exist. Thi
1db90 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f s is the behavio
1dba0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 r that is always
1dbb0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c used for.** sql
1dbc0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
1dbd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1dbe0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c .</dd>)^.** </dl
1dbf0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 >.**.** If the 3
1dc00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
1dc10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1dc20 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 ) is not one of
1dc30 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 the.** combinati
1dc40 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
1dc50 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 optionally combi
1dc60 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a ned with other.*
1dc70 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
1dc80 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 EADONLY | SQLITE
1dc90 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a _OPEN_* bits].**
1dca0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
1dcb0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
1dcc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b .**.** ^If the [
1dcd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
1dce0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
1dcf0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
1dd00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
1dd10 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d * opens in the m
1dd20 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
1dd30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 eading mode] as
1dd40 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 long as the sing
1dd50 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 le-thread.** mod
1dd60 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 e has not been s
1dd70 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
1dd80 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
1dd90 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 . ^If the.** [S
1dda0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
1ddb0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
1ddc0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 t then the datab
1ddd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
1dde0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 pens.** in the s
1ddf0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
1de00 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 ding mode] unles
1de10 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s single-thread
1de20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
1de30 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f y selected at co
1de40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
1de50 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 art-time..** ^Th
1de60 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 e [SQLITE_OPEN_S
1de70 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 HAREDCACHE] flag
1de80 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
1de90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1dea0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c to be.** eligibl
1deb0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 e to use [shared
1dec0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 cache mode], re
1ded0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
1dee0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
1def0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
1df00 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c abled using [sql
1df10 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
1df20 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 ed_cache()]. ^T
1df30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
1df40 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
1df50 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
1df60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1df70 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 tion to not.** p
1df80 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 articipate in [s
1df90 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
1dfa0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 ] even if it is
1dfb0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e enabled..**.** ^
1dfc0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
1dfd0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1dfe0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 open_v2() is the
1dff0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 name of the.**
1e000 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
1e010 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
1e020 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 s the operating
1e030 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 system interface
1e040 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 that.** the new
1e050 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1e060 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e tion should use.
1e070 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 ^If the fourth
1e080 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
1e090 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1e0a0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 then the default
1e0b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
1e0c0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a bject is used..*
1e0d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c *.** ^If the fil
1e0e0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 ename is ":memor
1e0f0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 y:", then a priv
1e100 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 ate, temporary i
1e110 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
1e120 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 e.** is created
1e130 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 for the connecti
1e140 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 on. ^This in-me
1e150 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 mory database wi
1e160 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a ll vanish when.*
1e170 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
1e180 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
1e190 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 sed. Future ver
1e1a0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
1e1b0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 might.** make us
1e1c0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 e of additional
1e1d0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 special filename
1e1e0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 s that begin wit
1e1f0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 h the ":" charac
1e200 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 ter..** It is re
1e210 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 commended that w
1e220 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 hen a database f
1e230 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 ilename actually
1e240 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 does begin with
1e250 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 .** a ":" charac
1e260 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 ter you should p
1e270 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 refix the filena
1e280 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 me with a pathna
1e290 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e me such as.** ".
1e2a0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 /" to avoid ambi
1e2b0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 guity..**.** ^If
1e2c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
1e2d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
1e2e0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
1e2f0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f , temporary.** o
1e300 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 n-disk database
1e310 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e will be created.
1e320 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 ^This private
1e330 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
1e340 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
1e350 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f y deleted as soo
1e360 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 n as the databas
1e370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
1e380 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b closed..**.** [[
1e390 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e URI filenames in
1e3a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d sqlite3_open()]
1e3b0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 ] <h3>URI Filena
1e3c0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e mes</h3>.**.** ^
1e3d0 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 If [URI filename
1e3e0 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e ] interpretation
1e3f0 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 is enabled, and
1e400 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
1e410 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 gument.** begins
1e420 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 with "file:", t
1e430 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 hen the filename
1e440 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
1e450 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a as a URI. ^URI.*
1e460 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 * filename inter
1e470 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
1e480 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c bled if the [SQL
1e490 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
1e4a0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 ag is.** set in
1e4b0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
1e4c0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ent to sqlite3_o
1e4d0 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 pen_v2(), or if
1e4e0 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 it has.** been e
1e4f0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 nabled globally
1e500 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
1e510 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 E_CONFIG_URI] op
1e520 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a tion with the.**
1e530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
1e540 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 ()] method or by
1e550 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 the [SQLITE_USE
1e560 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 _URI] compile-ti
1e570 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 me option..** As
1e580 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 of SQLite versi
1e590 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 on 3.7.7, URI fi
1e5a0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
1e5b0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ation is turned
1e5c0 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c off.** by defaul
1e5d0 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 t, but future re
1e5e0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
1e5f0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 might enable UR
1e600 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e I filename.** in
1e610 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 terpretation by
1e620 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b default. See "[
1e630 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 URI filenames]"
1e640 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
1e650 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
1e660 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d *.** URI filenam
1e670 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 es are parsed ac
1e680 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 cording to RFC 3
1e690 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 986. ^If the URI
1e6a0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 contains an.**
1e6b0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 authority, then
1e6c0 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 it must be eithe
1e6d0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e r an empty strin
1e6e0 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 g or the string
1e6f0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e .** "localhost".
1e700 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 ^If the authori
1e710 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 ty is not an emp
1e720 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f ty string or "lo
1e730 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a calhost", an .**
1e740 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
1e750 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 ed to the caller
1e760 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 . ^The fragment
1e770 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
1e780 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 RI, if .** prese
1e790 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a nt, is ignored..
1e7a0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
1e7b0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 es the path comp
1e7c0 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 onent of the URI
1e7d0 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 as the name of
1e7e0 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a the disk file.**
1e7f0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 which contains
1e800 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 the database. ^I
1e810 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e f the path begin
1e820 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 s with a '/' cha
1e830 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e racter, .** then
1e840 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 it is interpret
1e850 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 ed as an absolut
1e860 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 e path. ^If the
1e870 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 path does not be
1e880 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 gin .** with a '
1e890 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 /' (meaning that
1e8a0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 the authority s
1e8b0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 ection is omitte
1e8c0 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a d from the URI).
1e8d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 ** then the path
1e8e0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
1e8f0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 as a relative pa
1e900 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 th. .** ^On wind
1e910 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 ows, the first c
1e920 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 omponent of an a
1e930 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a bsolute path .**
1e940 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 is a drive spec
1e950 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 ification (e.g.
1e960 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 "C:")..**.** [[c
1e970 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 ore URI query pa
1e980 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 rameters]].** Th
1e990 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e e query componen
1e9a0 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 t of a URI may c
1e9b0 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 ontain parameter
1e9c0 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 s that are inter
1e9d0 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 preted.** either
1e9e0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c by SQLite itsel
1e9f0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 f, or by a [VFS
1ea00 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 | custom VFS imp
1ea10 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a lementation]..**
1ea20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 SQLite interpre
1ea30 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ts the following
1ea40 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 three query par
1ea50 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c ameters:.**.** <
1ea60 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 ul>.** <li> <b
1ea70 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 >vfs</b>: ^The "
1ea80 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d vfs" parameter m
1ea90 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 ay be used to sp
1eaa0 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f ecify the name o
1eab0 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f f.** a VFS o
1eac0 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 bject that provi
1ead0 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e des the operatin
1eae0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
1eaf0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a ce that should.*
1eb00 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f * be used to
1eb10 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
1eb20 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 base file on dis
1eb30 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 k. ^If this opti
1eb40 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 on is set to.**
1eb50 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 an empty str
1eb60 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 ing the default
1eb70 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 VFS object is us
1eb80 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 ed. ^Specifying
1eb90 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 an unknown.**
1eba0 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f VFS is an erro
1ebb0 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f r. ^If sqlite3_o
1ebc0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 pen_v2() is used
1ebd0 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 and the vfs opt
1ebe0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 ion is.** pr
1ebf0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 esent, then the
1ec00 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 VFS specified by
1ec10 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 the option take
1ec20 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 s precedence ove
1ec30 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c r.** the val
1ec40 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ue passed as the
1ec50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
1ec60 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
1ec70 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 n_v2()..**.**
1ec80 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e <li> <b>mode</b>
1ec90 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 : ^(The mode par
1eca0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 ameter may be se
1ecb0 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 t to either "ro"
1ecc0 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20 , "rw" or.**
1ecd0 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69 "rwc". Attempti
1ece0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 ng to set it to
1ecf0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 any other value
1ed00 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a is an error)^. .
1ed10 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 ** ^If "ro"
1ed20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 is specified, th
1ed30 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
1ed40 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
1ed50 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 ad-only .**
1ed60 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 access, just as
1ed70 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
1ed80 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c PEN_READONLY] fl
1ed90 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 ag had been set
1eda0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 in the .** t
1edb0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
1edc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1edd0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d _v2(). ^If the m
1ede0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ode option is se
1edf0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 t to .** "rw
1ee00 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 ", then the data
1ee10 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
1ee20 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 or read-write (b
1ee30 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a ut not create) .
1ee40 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 ** access, a
1ee50 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e s if SQLITE_OPEN
1ee60 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 _READWRITE (but
1ee70 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f not SQLITE_OPEN_
1ee80 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 CREATE) had .**
1ee90 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 been set. ^V
1eea0 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 alue "rwc" is eq
1eeb0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
1eec0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 ing both .**
1eed0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
1eee0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 DWRITE and SQLIT
1eef0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e E_OPEN_CREATE. ^
1ef00 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f If sqlite3_open_
1ef10 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20 v2() is .**
1ef20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65 used, it is an e
1ef30 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 rror to specify
1ef40 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 a value for the
1ef50 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 mode parameter t
1ef60 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c hat is .** l
1ef70 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 ess restrictive
1ef80 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 than that specif
1ef90 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67 73 ied by the flags
1efa0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
1efb0 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72 hird .** par
1efc0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 ameter..**.**
1efd0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 <li> <b>cache</b
1efe0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 >: ^The cache pa
1eff0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
1f000 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 et to either "sh
1f010 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 ared" or.**
1f020 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 "private". ^Sett
1f030 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 ing it to "share
1f040 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 d" is equivalent
1f050 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a to setting the.
1f060 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
1f070 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 EN_SHAREDCACHE b
1f080 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 it in the flags
1f090 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
1f0a0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 to.** sqlite
1f0b0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 3_open_v2(). ^Se
1f0c0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 tting the cache
1f0d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 parameter to "pr
1f0e0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 ivate" is .**
1f0f0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 equivalent to
1f100 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 setting the SQLI
1f110 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
1f120 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 ACHE bit..**
1f130 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 ^If sqlite3_ope
1f140 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 n_v2() is used a
1f150 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 nd the "cache" p
1f160 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 arameter is pres
1f170 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 ent in.** a
1f180 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 URI filename, it
1f190 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 s value override
1f1a0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 s any behaviour
1f1b0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 requested by set
1f1c0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 ting.** SQLI
1f1d0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
1f1e0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f ACHE or SQLITE_O
1f1f0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 PEN_SHAREDCACHE
1f200 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a flag..** </ul>.*
1f210 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 *.** ^Specifying
1f220 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 an unknown para
1f230 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 meter in the que
1f240 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 ry component of
1f250 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a a URI is not an.
1f260 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 ** error. Futur
1f270 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
1f280 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 Lite might under
1f290 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c stand additional
1f2a0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 query.** parame
1f2b0 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 ters. See "[que
1f2c0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 ry parameters wi
1f2d0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 th special meani
1f2e0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 ng to SQLite]" f
1f2f0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c or.** additional
1f300 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
1f310 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 .** [[URI filena
1f320 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 me examples]] <h
1f330 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 3>URI filename e
1f340 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a xamples</h3>.**.
1f350 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
1f360 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 ="1" align=cente
1f370 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e r cellpadding=5>
1f380 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 .** <tr><th> URI
1f390 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 filenames <th>
1f3a0 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c Results.** <tr><
1f3b0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
1f3c0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
1f3d0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 Open the file
1f3e0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
1f3f0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
1f400 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ory..** <tr><td>
1f410 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
1f420 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 /data.db<br>.**
1f430 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
1f440 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
1f450 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 db <br> .**
1f460 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 file://loca
1f470 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f lhost/home/fred/
1f480 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 data.db <br> <td
1f490 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
1f4a0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
1f4b0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 file "/home/fre
1f4c0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c d/data.db"..** <
1f4d0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 tr><td> file://d
1f4e0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 arkstar/home/fre
1f4f0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a d/data.db <td> .
1f500 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 ** An e
1f510 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 rror. "darkstar"
1f520 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e is not a recogn
1f530 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a ized authority..
1f540 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 ** <tr><td style
1f550 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f ="white-space:no
1f560 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 wrap"> .**
1f570 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 file:///C:/D
1f580 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 ocuments%20and%2
1f590 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 0Settings/fred/D
1f5a0 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a esktop/data.db.*
1f5b0 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f * <td> Windo
1f5c0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 ws only: Open th
1f5d0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 e file "data.db"
1f5e0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 on fred's deskt
1f5f0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 op on drive.**
1f600 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 C:. Note
1f610 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 that the %20 es
1f620 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 caping in this e
1f630 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 xample is not st
1f640 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 rictly .**
1f650 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 necessary -
1f660 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 space characters
1f670 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 can be used lit
1f680 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 erally.**
1f690 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 in URI filena
1f6a0 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e mes..** <tr><td>
1f6b0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f file:data.db?mo
1f6c0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 de=ro&cache=priv
1f6d0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 ate <td> .**
1f6e0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 Open file
1f6f0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
1f700 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
1f710 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 ry for read-only
1f720 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 access..**
1f730 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 Regardless
1f740 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
1f750 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d t shared-cache m
1f760 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 ode is enabled b
1f770 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 y.** de
1f780 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 fault, use a pri
1f790 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c vate cache..** <
1f7a0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f tr><td> file:/ho
1f7b0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f me/fred/data.db?
1f7c0 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 vfs=unix-nolock
1f7d0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 <td>.**
1f7e0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d Open file "/hom
1f7f0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e e/fred/data.db".
1f800 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c Use the special
1f810 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 VFS "unix-noloc
1f820 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 k"..** <tr><td>
1f830 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 file:data.db?mod
1f840 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 e=readonly <td>
1f850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 .** An
1f860 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 error. "readonly
1f870 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 " is not a valid
1f880 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 option for the
1f890 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 "mode" parameter
1f8a0 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a ..** </table>.**
1f8b0 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 .** ^URI hexadec
1f8c0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 imal escape sequ
1f8d0 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 ences (%HH) are
1f8e0 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e supported within
1f8f0 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a the path and.**
1f900 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
1f910 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 s of a URI. A he
1f920 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
1f930 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 sequence consis
1f940 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 ts of a.** perce
1f950 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 nt sign - "%" -
1f960 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 followed by exac
1f970 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 tly two hexadeci
1f980 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 mal digits .** s
1f990 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 pecifying an oct
1f9a0 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 et value. ^Befor
1f9b0 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 e the path or qu
1f9c0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
1f9d0 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e f a.** URI filen
1f9e0 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 ame are interpre
1f9f0 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e ted, they are en
1fa00 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d coded using UTF-
1fa10 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 8 and all .** he
1fa20 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
1fa30 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 sequences repla
1fa40 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 ced by a single
1fa50 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 byte containing
1fa60 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e the.** correspon
1fa70 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 ding octet. If t
1fa80 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 his process gene
1fa90 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 rates an invalid
1faa0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c UTF-8 encoding,
1fab0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 .** the results
1fac0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
1fad0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 *.** <b>Note to
1fae0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f Windows users:</
1faf0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 b> The encoding
1fb00 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 used for the fi
1fb10 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
1fb20 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 ** of sqlite3_op
1fb30 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
1fb40 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 _open_v2() must
1fb50 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 be UTF-8, not wh
1fb60 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 atever.** codepa
1fb70 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 ge is currently
1fb80 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 defined. Filena
1fb90 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 mes containing i
1fba0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 nternational.**
1fbb0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 characters must
1fbc0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 be converted to
1fbd0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 UTF-8 prior to p
1fbe0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f assing them into
1fbf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
1fc00 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 () or sqlite3_op
1fc10 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 en_v2()..*/.SQLI
1fc20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1fc30 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 e3_open(. const
1fc40 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c char *filename,
1fc50 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 /* Database f
1fc60 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 ilename (UTF-8)
1fc70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
1fc80 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb /*
1fc90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
1fca0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 andle */.);.SQLI
1fcb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1fcc0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e e3_open16(. con
1fcd0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d st void *filenam
1fce0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 e, /* Database
1fcf0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 filename (UTF-1
1fd00 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 6) */. sqlite3
1fd10 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
1fd20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
1fd30 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 b handle */.);.S
1fd40 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1fd50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 lite3_open_v2(.
1fd60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
1fd70 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
1fd80 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
1fd90 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
1fda0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 e3 **ppDb,
1fdb0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
1fdc0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 e db handle */.
1fdd0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 int flags,
1fde0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 /* Flag
1fdf0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 s */. const cha
1fe00 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f r *zVfs /
1fe10 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f * Name of VFS mo
1fe20 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 dule to use */.)
1fe30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1fe40 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 F: Obtain Values
1fe50 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 For URI Paramet
1fe60 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ers.**.** These
1fe70 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 are utility rout
1fe80 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 ines, useful to
1fe90 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
1fea0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a ons, that check.
1feb0 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 ** to see if a d
1fec0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 atabase file was
1fed0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 a URI that cont
1fee0 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 ained a specific
1fef0 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d query .** param
1ff00 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 eter, and if so
1ff10 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 obtains the valu
1ff20 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 e of that query
1ff30 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
1ff40 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 If F is the dat
1ff50 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 abase filename p
1ff60 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e ointer passed in
1ff70 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d to the xOpen() m
1ff80 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 ethod of .** a V
1ff90 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
1ffa0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 n when the flags
1ffb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
1ffc0 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 pen() has one or
1ffd0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 .** more of the
1ffe0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
1fff0 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 I] or [SQLITE_OP
20000 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 EN_MAIN_DB] bits
20010 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 set and.** P is
20020 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
20030 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
20040 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
20050 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
20060 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 F,P) returns the
20070 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a value of the P.
20080 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 ** parameter if
20090 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e it exists or a N
200a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 ULL pointer if P
200b0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 does not appear
200c0 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 as a .** query
200d0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 parameter on F.
200e0 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 If P is a query
200f0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a parameter of F.
20100 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 ** has no explic
20110 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 it value, then s
20120 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
20130 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
20140 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 s.** a pointer t
20150 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e o an empty strin
20160 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c g..**.** The sql
20170 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
20180 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
20190 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 assumes that P i
201a0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 s a boolean.** p
201b0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
201c0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 urns true (1) or
201d0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 false (0) accor
201e0 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 ding to the valu
201f0 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 e.** of P. The
20200 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 74 72 value of P is tr
20210 75 65 20 69 66 20 69 74 20 69 73 20 22 79 65 73 ue if it is "yes
20220 22 20 6f 72 20 22 74 72 75 65 22 20 6f 72 20 22 " or "true" or "
20230 6f 6e 22 20 6f 72 20 0a 2a 2a 20 61 20 6e 6f 6e on" or .** a non
20240 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 20 61 6e 64 -zero number and
20250 20 69 73 20 66 61 6c 73 65 20 6f 74 68 65 72 77 is false otherw
20260 69 73 65 2e 20 20 49 66 20 50 20 69 73 20 6e 6f ise. If P is no
20270 74 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 t a query parame
20280 74 65 72 0a 2a 2a 20 6f 6e 20 46 20 74 68 65 6e ter.** on F then
20290 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
202a0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
202b0 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a rns (B!=0)..**.*
202c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 * The sqlite3_ur
202d0 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 i_int64(F,P,D) r
202e0 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 outine converts
202f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
20300 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 nto a.** 64-bit
20310 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 signed integer a
20320 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 nd returns that
20330 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 integer, or D if
20340 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 P does not.** e
20350 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 xist. If the va
20360 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 lue of P is some
20370 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
20380 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 an integer, the
20390 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 n.** zero is ret
203a0 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 urned..** .** If
203b0 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 F is a NULL poi
203c0 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 nter, then sqlit
203d0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
203e0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 (F,P) returns NU
203f0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 LL and.** sqlite
20400 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
20410 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 P,B) returns B.
20420 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e If F is not a N
20430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a ULL pointer and.
20440 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 ** is not a data
20450 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 base file pathna
20460 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 me pointer that
20470 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e SQLite passed in
20480 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 to the xOpen.**
20490 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e VFS method, then
204a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
204b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
204c0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
204d0 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 robably.** undes
204e0 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 irable..*/.SQLIT
204f0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
20500 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 *sqlite3_uri_pa
20510 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 rameter(const ch
20520 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 ar *zFilename, c
20530 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
20540 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 m);.SQLITE_API i
20550 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 nt sqlite3_uri_b
20560 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 oolean(const cha
20570 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 r *zFile, const
20580 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e char *zParam, in
20590 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c t bDefault);.SQL
205a0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
205b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 int64 sqlite3_ur
205c0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 i_int64(const ch
205d0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a ar*, const char*
205e0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
205f0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
20600 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
20610 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a And Messages.**.
20620 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
20630 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 errcode() interf
20640 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
20650 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
20660 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
20670 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
20680 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 e] for the most
20690 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 recent failed sq
206a0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
206b0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
206c0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
206d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 connection]. If
206e0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c a prior API call
206f0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 failed.** but t
20700 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
20710 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 PI call succeede
20720 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 d, the return va
20730 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 lue from.** sqli
20740 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 te3_errcode() is
20750 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 undefined. ^Th
20760 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
20770 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
20780 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
20790 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
207a0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
207b0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
207c0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
207d0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
207e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
207f0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
20800 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
20810 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
20820 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
20830 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
20840 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
20850 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
20860 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
20870 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
20880 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
20890 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 ctively..** ^(Me
208a0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
208b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
208c0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
208d0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 internally..**
208e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
208f0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
20900 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 worry about fre
20910 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e eing the result.
20920 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
20930 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 error string mi
20940 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 ght be overwritt
20950 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
20960 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 d by.** subseque
20970 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 nt calls to othe
20980 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
20990 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a ce functions.)^.
209a0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 **.** When the s
209b0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
209c0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e ding mode] is in
209d0 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 use, it might b
209e0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 e the.** case th
209f0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f at a second erro
20a00 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 r occurs on a se
20a10 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e parate thread in
20a20 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
20a30 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 time of the firs
20a40 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 t error and the
20a50 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e call to these in
20a60 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 terfaces..** Whe
20a70 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 n that happens,
20a80 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 the second error
20a90 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 will be reporte
20aa0 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a d since these.**
20ab0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 interfaces alwa
20ac0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f ys report the mo
20ad0 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 st recent result
20ae0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 . To avoid.** t
20af0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 his, each thread
20b00 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c can obtain excl
20b10 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 usive use of the
20b20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
20b30 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 ction] D.** by i
20b40 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
20b50 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 _mutex_enter]([s
20b60 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
20b70 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 (D)) before begi
20b80 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 nning.** to use
20b90 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b D and invoking [
20ba0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
20bb0 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ave]([sqlite3_db
20bc0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 _mutex](D)) afte
20bd0 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 r.** all calls t
20be0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 o the interfaces
20bf0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 listed here are
20c00 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a completed..**.*
20c10 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 * If an interfac
20c20 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c e fails with SQL
20c30 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 ITE_MISUSE, that
20c40 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 means the inter
20c50 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f face.** was invo
20c60 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ked incorrectly
20c70 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
20c80 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 on. In that cas
20c90 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 e, the.** error
20ca0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
20cb0 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 may or may not
20cc0 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 be set..*/.SQLIT
20cd0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
20ce0 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 3_errcode(sqlite
20cf0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 3 *db);.SQLITE_A
20d00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
20d10 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
20d20 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 sqlite3 *db);.SQ
20d30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
20d40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 har *sqlite3_err
20d50 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 msg(sqlite3*);.S
20d60 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
20d70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 void *sqlite3_er
20d80 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 rmsg16(sqlite3*)
20d90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20da0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 F: SQL Statement
20db0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
20dc0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 RDS: {prepared s
20dd0 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 tatement} {prepa
20de0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a red statements}.
20df0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
20e00 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
20e10 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 represents a si
20e20 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 ngle SQL stateme
20e30 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 nt..** This obje
20e40 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 ct is variously
20e50 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 known as a "prep
20e60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 ared statement"
20e70 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 or a.** "compile
20e80 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 d SQL statement"
20e90 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 or simply as a
20ea0 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a "statement"..**.
20eb0 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 ** The life of a
20ec0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 statement objec
20ed0 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 t goes something
20ee0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
20ef0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 * <ol>.** <li> C
20f00 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 reate the object
20f10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
20f20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
20f30 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 a related.**
20f40 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 function..**
20f50 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 <li> Bind values
20f60 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 to [host parame
20f70 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 ters] using the
20f80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
20f90 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 .** interfa
20fa0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e ces..** <li> Run
20fb0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c the SQL by call
20fc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
20fd0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 p()] one or more
20fe0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
20ff0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d Reset the statem
21000 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ent using [sqlit
21010 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e e3_reset()] then
21020 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 go back.**
21030 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 to step 2. Do
21040 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 this zero or mor
21050 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e e times..** <li>
21060 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a Destroy the obj
21070 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
21080 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
21090 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 ** </ol>.**.** R
210a0 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 efer to document
210b0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 ation on individ
210c0 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 ual methods abov
210d0 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c e for additional
210e0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
210f0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
21100 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ct sqlite3_stmt
21110 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f sqlite3_stmt;../
21120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
21130 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a un-time Limits.*
21140 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 *.** ^(This inte
21150 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 rface allows the
21160 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 size of various
21170 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 constructs to b
21180 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 e limited.** on
21190 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 a connection by
211a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
211b0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
211c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
211d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
211e0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d ction] whose lim
211f0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 it is to be set
21200 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 or queried. The
21210 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
21220 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 eter is one of t
21230 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f he [limit catego
21240 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e ries] that defin
21250 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 e a.** class of
21260 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
21270 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 size limited.
21280 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
21290 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 ter is the.** ne
212a0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 w limit for that
212b0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a construct.)^.**
212c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 .** ^If the new
212d0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
212e0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
212f0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
21300 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 ed..** ^(For eac
21310 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 h limit category
21320 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 SQLITE_LIMIT_<i
21330 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 >NAME</i> there
21340 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 is a .** [limits
21350 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f | hard upper bo
21360 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 und].** set at c
21370 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 ompile-time by a
21380 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
21390 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 macro called.**
213a0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 [limits | SQLITE
213b0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e _MAX_<i>NAME</i>
213c0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d ]..** (The "_LIM
213d0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 IT_" in the name
213e0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 is changed to "
213f0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 _MAX_".))^.** ^A
21400 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 ttempts to incre
21410 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 ase a limit abov
21420 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 e its hard upper
21430 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 bound are.** si
21440 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
21450 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 to the hard upp
21460 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 er bound..**.**
21470 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 ^Regardless of w
21480 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
21490 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e e limit was chan
214a0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 ged, the .** [sq
214b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 lite3_limit()] i
214c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
214d0 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
214e0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a of the limit..*
214f0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e * ^Hence, to fin
21500 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 d the current va
21510 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 lue of a limit w
21520 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 ithout changing
21530 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e it,.** simply in
21540 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 voke this interf
21550 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 ace with the thi
21560 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 rd parameter set
21570 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 to -1..**.** Ru
21580 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 n-time limits ar
21590 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
215a0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f se in applicatio
215b0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a ns that manage.*
215c0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e * both their own
215d0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
215e0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 se and also data
215f0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 bases that are c
21600 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 ontrolled.** by
21610 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e untrusted extern
21620 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 al sources. An
21630 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 example applicat
21640 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a ion might be a.*
21650 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 * web browser th
21660 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 at has its own d
21670 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f atabases for sto
21680 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 ring history and
21690 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 .** separate dat
216a0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 abases controlle
216b0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 d by JavaScript
216c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 applications dow
216d0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 nloaded.** off t
216e0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 he Internet. Th
216f0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 e internal datab
21700 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 ases can be give
21710 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 n the.** large,
21720 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 default limits.
21730 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 Databases manag
21740 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 ed by external s
21750 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 ources can.** be
21760 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c given much smal
21770 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 ler limits desig
21780 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 ned to prevent a
21790 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 denial of servi
217a0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 ce.** attack. D
217b0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 evelopers might
217c0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 also want to use
217d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 the [sqlite3_se
217e0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a t_authorizer()].
217f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 ** interface to
21800 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 further control
21810 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 untrusted SQL.
21820 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
21830 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 database.** crea
21840 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 ted by an untrus
21850 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 ted script can b
21860 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e e contained usin
21870 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 g the.** [max_pa
21880 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
21890 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 A]..**.** New ru
218a0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 n-time limit cat
218b0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 egories may be a
218c0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
218d0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 eleases..*/.SQLI
218e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
218f0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 e3_limit(sqlite3
21900 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e *, int id, int n
21910 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ewVal);../*.** C
21920 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
21930 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 e Limit Categori
21940 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
21950 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d {limit category}
21960 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 {*limit categor
21970 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ies}.**.** These
21980 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
21990 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 e various perfor
219a0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 mance limits.**
219b0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 that can be lowe
219c0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 red at run-time
219d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
219e0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 imit()]..** The
219f0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 synopsis of the
21a00 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 meanings of the
21a10 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 various limits i
21a20 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a s shown below..*
21a30 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 * Additional inf
21a40 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 ormation is avai
21a50 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 lable at [limits
21a60 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c | Limits in SQL
21a70 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e ite]..**.** <dl>
21a80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
21a90 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 IT_LENGTH]] ^(<d
21aa0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
21ab0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
21ac0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 d>The maximum si
21ad0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 ze of any string
21ae0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c or BLOB or tabl
21af0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e e row, in bytes.
21b00 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 <dd>)^.**.** [[S
21b10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
21b20 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 LENGTH]] ^(<dt>S
21b30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
21b40 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
21b50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
21b60 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 ength of an SQL
21b70 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 statement, in by
21b80 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a tes.</dd>)^.**.*
21b90 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
21ba0 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e _COLUMN]] ^(<dt>
21bb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
21bc0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e UMN</dt>.** <dd>
21bd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
21be0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
21bf0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 a table definit
21c00 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a ion or in the.**
21c10 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 result set of a
21c20 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 [SELECT] or the
21c30 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
21c40 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e of columns in an
21c50 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 index.** or in
21c60 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 an ORDER BY or G
21c70 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c ROUP BY clause.<
21c80 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
21c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
21ca0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 _DEPTH]] ^(<dt>S
21cb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
21cc0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c _DEPTH</dt>.** <
21cd0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 dd>The maximum d
21ce0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 epth of the pars
21cf0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 e tree on any ex
21d00 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e pression.</dd>)^
21d10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
21d20 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 LIMIT_COMPOUND_S
21d30 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 ELECT]] ^(<dt>SQ
21d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
21d50 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a UND_SELECT</dt>.
21d60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
21d70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 um number of ter
21d80 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 ms in a compound
21d90 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
21da0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 t.</dd>)^.**.**
21db0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [[SQLITE_LIMIT_V
21dc0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 DBE_OP]] ^(<dt>S
21dd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
21de0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e _OP</dt>.** <dd>
21df0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
21e00 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f er of instructio
21e10 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 ns in a virtual
21e20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a machine program.
21e30 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 ** used to imple
21e40 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 ment an SQL stat
21e50 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d ement. This lim
21e60 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e it is not curren
21e70 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c tly.** enforced,
21e80 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 though that mig
21e90 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 ht be added in s
21ea0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 ome future relea
21eb0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e se of.** SQLite.
21ec0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
21ed0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
21ee0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 CTION_ARG]] ^(<d
21ef0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 t>SQLITE_LIMIT_F
21f00 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e UNCTION_ARG</dt>
21f10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
21f20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 mum number of ar
21f30 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e guments on a fun
21f40 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ction.</dd>)^.**
21f50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
21f60 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 IT_ATTACHED]] ^(
21f70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
21f80 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a _ATTACHED</dt>.*
21f90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
21fa0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 m number of [ATT
21fb0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 ACH | attached d
21fc0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 atabases].)^</dd
21fd0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
21fe0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
21ff0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 ERN_LENGTH]].**
22000 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
22010 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
22020 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
22030 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
22040 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 ength of the pat
22050 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f tern argument to
22060 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a the [LIKE] or.*
22070 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f * [GLOB] operato
22080 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a rs.</dd>)^.**.**
22090 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
220a0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
220b0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 ].** ^(<dt>SQLIT
220c0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
220d0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 _NUMBER</dt>.**
220e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
220f0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 index number of
22100 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 any [parameter]
22110 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d in an SQL statem
22120 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ent.)^.**.** [[S
22130 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
22140 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 GER_DEPTH]] ^(<d
22150 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 t>SQLITE_LIMIT_T
22160 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 RIGGER_DEPTH</dt
22170 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
22180 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 imum depth of re
22190 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 cursion for trig
221a0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 gers.</dd>)^.**
221b0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
221c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 SQLITE_LIMIT_LE
221d0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
221e0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
221f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 e SQLITE_LIMIT_S
22200 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 QL_LENGTH
22210 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
22220 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
22230 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 COLUMN
22240 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 2.#def
22250 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
22260 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 _EXPR_DEPTH
22270 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 3.#de
22280 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
22290 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
222a0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 T 4.#d
222b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
222c0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 IT_VDBE_OP
222d0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
222e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
222f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
22300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
22310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
22320 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 IMIT_ATTACHED
22330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 7
22340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22350 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
22360 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 RN_LENGTH
22370 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
22380 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
22390 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 NUMBER
223a0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 9.#define SQLIT
223b0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
223c0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
223d0 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 10../*.** CAPI3
223e0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 REF: Compiling A
223f0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a n SQL Statement.
22400 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
22410 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 L statement comp
22420 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 iler}.**.** To e
22430 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 xecute an SQL qu
22440 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 ery, it must fir
22450 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 st be compiled i
22460 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a nto a byte-code.
22470 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 ** program using
22480 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f one of these ro
22490 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
224a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
224b0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 , "db", is a [da
224c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
224d0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d n] obtained from
224e0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 a.** prior succ
224f0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
22500 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
22510 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
22520 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 2()] or.** [sqli
22530 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 te3_open16()].
22540 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
22550 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
22560 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 have been close
22570 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 d..**.** The sec
22580 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a ond argument, "z
22590 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 Sql", is the sta
225a0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
225b0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a piled, encoded.*
225c0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d * as either UTF-
225d0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 8 or UTF-16. Th
225e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
225f0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
22600 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 prepare_v2().**
22610 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 interfaces use U
22620 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 TF-8, and sqlite
22630 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 3_prepare16() an
22640 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
22650 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 e16_v2().** use
22660 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 UTF-16..**.** ^I
22670 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 f the nByte argu
22680 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 ment is less tha
22690 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 n zero, then zSq
226a0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 l is read up to
226b0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 the.** first zer
226c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 o terminator. ^I
226d0 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e f nByte is non-n
226e0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 egative, then it
226f0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a is the maximum.
22700 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 ** number of by
22710 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 tes read from zS
22720 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 ql. ^When nByte
22730 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
22740 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 , the.** zSql st
22750 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 ring ends at eit
22760 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c her the first '\
22770 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 000' or '\u0000'
22780 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a character or.**
22790 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 the nByte-th by
227a0 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f te, whichever co
227b0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 mes first. If th
227c0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a e caller knows.*
227d0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c * that the suppl
227e0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 ied string is nu
227f0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 l-terminated, th
22800 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d en there is a sm
22810 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e all.** performan
22820 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 ce advantage to
22830 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 be gained by pas
22840 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 sing an nByte pa
22850 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 rameter that.**
22860 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 is equal to the
22870 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
22880 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 in the input str
22890 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 ing <i>including
228a0 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d </i>.** the nul-
228b0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 terminator bytes
228c0 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 as this saves S
228d0 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e QLite from havin
228e0 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 g to.** make a c
228f0 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 opy of the input
22900 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e string..**.** ^
22910 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 If pzTail is not
22920 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 NULL then *pzTa
22930 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f il is made to po
22940 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 int to the first
22950 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 byte.** past th
22960 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 e end of the fir
22970 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
22980 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 in zSql. These
22990 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a routines only.*
229a0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 * compile the fi
229b0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e rst statement in
229c0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 zSql, so *pzTai
229d0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 l is left pointi
229e0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 ng to.** what re
229f0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 mains uncompiled
22a00 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 ..**.** ^*ppStmt
22a10 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
22a20 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 g to a compiled
22a30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
22a40 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 ent] that can be
22a50 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 .** executed usi
22a60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
22a70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 ()]. ^If there
22a80 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 is an error, *pp
22a90 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 Stmt is set.** t
22aa0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 o NULL. ^If the
22ab0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 input text cont
22ac0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 ains no SQL (if
22ad0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 the input is an
22ae0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 empty.** string
22af0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 or a comment) th
22b00 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 en *ppStmt is se
22b10 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 t to NULL..** Th
22b20 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 e calling proced
22b30 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ure is responsib
22b40 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 le for deleting
22b50 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 the compiled.**
22b60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 SQL statement us
22b70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
22b80 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 alize()] after i
22b90 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 t has finished w
22ba0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d ith it..** ppStm
22bb0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c t may not be NUL
22bc0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 L..**.** ^On suc
22bd0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 cess, the sqlite
22be0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 3_prepare() fami
22bf0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 ly of routines r
22c00 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
22c10 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 ];.** otherwise
22c20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
22c30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
22c40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 ** The sqlite3_p
22c50 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 repare_v2() and
22c60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
22c70 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 6_v2() interface
22c80 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 s are.** recomme
22c90 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 nded for all new
22ca0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 programs. The t
22cb0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 wo older interfa
22cc0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 ces are retained
22cd0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 .** for backward
22ce0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c s compatibility,
22cf0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 but their use i
22d00 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a s discouraged..*
22d10 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 * ^In the "v2" i
22d20 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
22d30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
22d40 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
22d50 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
22d60 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
22d70 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
22d80 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 y of the.** orig
22d90 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 inal SQL text. T
22da0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b his causes the [
22db0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
22dc0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 interface to.**
22dd0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 behave different
22de0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 ly in three ways
22df0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
22e00 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
22e10 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
22e20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 changes, instead
22e30 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 of returning [S
22e40 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 QLITE_SCHEMA] as
22e50 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 it.** always us
22e60 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 ed to do, [sqlit
22e70 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
22e80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
22e90 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a compile the SQL.
22ea0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ** statement and
22eb0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 try to run it a
22ec0 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a gain..** </li>.*
22ed0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 *.** <li>.** ^Wh
22ee0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
22ef0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
22f00 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
22f10 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
22f20 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
22f30 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
22f40 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
22f50 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 ^The legacy be
22f60 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a havior was that.
22f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
22f80 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 ()] would only r
22f90 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 eturn a generic
22fa0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 [SQLITE_ERROR] r
22fb0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e esult code.** an
22fc0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
22fd0 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 n would have to
22fe0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 make a second ca
22ff0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ll to [sqlite3_r
23000 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 eset()].** in or
23010 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 der to find the
23020 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 underlying cause
23030 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e of the problem.
23040 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
23050 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 repare.** interf
23060 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c aces, the underl
23070 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 ying reason for
23080 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 the error is ret
23090 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
230a0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a y..** </li>.**.*
230b0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
230c0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
230d0 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d bound to [param
230e0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 eter | host para
230f0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a meter] in the .*
23100 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d * WHERE clause m
23110 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 ight influence t
23120 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 he choice of que
23130 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 ry plan for a st
23140 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e atement,.** then
23150 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
23160 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
23170 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c ally recompiled,
23180 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 as if there had
23190 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 been .** a sche
231a0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 ma change, on th
231b0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 e first [sqlite
231c0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 3_step()] call f
231d0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 ollowing any cha
231e0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 nge.** to the [s
231f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
23200 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 | bindings] of
23210 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d that [parameter]
23220 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 . .** ^The speci
23230 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 fic value of WHE
23240 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d RE-clause [param
23250 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c eter] might infl
23260 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 uence the .** ch
23270 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
23280 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 an if the parame
23290 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d ter is the left-
232a0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b hand side of a [
232b0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f LIKE].** or [GLO
232c0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 B] operator or i
232d0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
232e0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 is compared to a
232f0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e n indexed column
23300 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c .** and the [SQL
23310 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 ITE_ENABLE_STAT3
23320 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
23330 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ption is enabled
23340 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c ..** the .** </l
23350 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 i>.** </ol>.*/.S
23360 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
23370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
23380 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
23390 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
233a0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
233b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
233c0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
233d0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
233e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
233f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
23400 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
23410 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
23420 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
23430 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
23440 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
23450 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
23460 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
23470 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
23480 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
23490 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
234a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c f zSql */.);.SQL
234b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
234c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a te3_prepare_v2(.
234d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
234e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
234f0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
23500 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
23510 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
23520 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
23530 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
23540 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
23550 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
23560 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
23570 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
23580 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
23590 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
235a0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
235b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
235c0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
235d0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
235e0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
235f0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
23600 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
23610 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
23620 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
23630 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
23640 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
23650 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
23660 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
23670 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
23680 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
23690 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
236a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
236b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
236c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
236d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
236e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
236f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
23700 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
23710 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
23720 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
23730 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
23740 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 of zSql */.);.S
23750 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
23760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
23770 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
23780 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
23790 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
237a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
237b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
237c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
237d0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
237e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
237f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
23800 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
23810 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
23820 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
23830 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
23840 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
23850 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
23860 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
23870 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
23880 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
23890 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
238a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
238b0 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 EF: Retrieving S
238c0 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a tatement SQL.**.
238d0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 ** ^This interfa
238e0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ce can be used t
238f0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 o retrieve a sav
23900 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f ed copy of the o
23910 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 riginal.** SQL t
23920 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 ext used to crea
23930 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
23940 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 tatement] if tha
23950 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a t statement was.
23960 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e ** compiled usin
23970 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
23980 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
23990 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
239a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a are16_v2()]..*/.
239b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
239c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 char *sqlite3_s
239d0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ql(sqlite3_stmt
239e0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
239f0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
23a00 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 ine If An SQL St
23a10 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 atement Writes T
23a20 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a he Database.**.*
23a30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
23a40 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 tmt_readonly(X)
23a50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
23a60 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
23a70 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 ) if.** and only
23a80 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 if the [prepare
23a90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d d statement] X m
23aa0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 akes no direct c
23ab0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 hanges to.** the
23ac0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
23ad0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a database file..*
23ae0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b *.** Note that [
23af0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
23b00 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
23b10 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 s] or.** [virtua
23b20 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 l tables] might
23b30 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
23b40 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 ase indirectly a
23b50 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e s a side effect.
23b60 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d .** ^(For exam
23b70 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 ple, if an appli
23b80 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 cation defines a
23b90 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 function "eval(
23ba0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c )" that .** call
23bb0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 s [sqlite3_exec(
23bc0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c )], then the fol
23bd0 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 lowing SQL state
23be0 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 ment would.** ch
23bf0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 ange the databas
23c00 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 e file through s
23c10 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a ide-effects:.**.
23c20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
23c30 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 pre>.** SELEC
23c40 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 T eval('DELETE F
23c50 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 ROM t1') FROM t2
23c60 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
23c70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 ckquote>.**.** B
23c80 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b ut because the [
23c90 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
23ca0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 t does not chang
23cb0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 e the database f
23cc0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c ile.** directly,
23cd0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
23ce0 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 adonly() would s
23cf0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 till return true
23d00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 .)^.**.** ^Trans
23d10 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 action control s
23d20 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 tatements such a
23d30 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d s [BEGIN], [COMM
23d40 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c IT], [ROLLBACK],
23d50 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c .** [SAVEPOINT],
23d60 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 and [RELEASE] c
23d70 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ause sqlite3_stm
23d80 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
23d90 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 return true,.**
23da0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d since the statem
23db0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 ents themselves
23dc0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 do not actually
23dd0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 modify the datab
23de0 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 ase but.** rathe
23df0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 r they control t
23e00 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 he timing of whe
23e10 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e n other statemen
23e20 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a ts modify the .*
23e30 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 * database. ^Th
23e40 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b e [ATTACH] and [
23e50 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e DETACH] statemen
23e60 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a ts also cause.**
23e70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
23e80 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 adonly() to retu
23e90 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 rn true since, w
23ea0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 hile those state
23eb0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 ments.** change
23ec0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
23ed0 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 n of a database
23ee0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 connection, they
23ef0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a do not make .**
23f00 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
23f10 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 content of the d
23f20 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e atabase files on
23f30 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 disk..*/.SQLITE
23f40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
23f50 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 _stmt_readonly(s
23f60 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
23f70 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
23f80 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
23f90 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 If A Prepared St
23fa0 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e atement Has Been
23fb0 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 Reset.**.** ^Th
23fc0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 e sqlite3_stmt_b
23fd0 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 usy(S) interface
23fe0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e returns true (n
23ff0 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a on-zero) if the.
24000 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
24010 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 tement] S has be
24020 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 en stepped at le
24030 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a ast once using .
24040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
24050 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 (S)] but has not
24060 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 run to completi
24070 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f on and/or has no
24080 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 t .** been reset
24090 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
240a0 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 reset(S)]. ^The
240b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
240c0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 sy(S).** interfa
240d0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 ce returns false
240e0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 if S is a NULL
240f0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 pointer. If S i
24100 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c s not a .** NULL
24110 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 pointer and is
24120 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f not a pointer to
24130 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 a valid [prepar
24140 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
24150 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 object, then th
24160 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
24170 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
24180 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 ably undesirable
24190 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
241a0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
241b0 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f ed in combinatio
241c0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f n [sqlite3_next_
241d0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f stmt()].** to lo
241e0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 cate all prepare
241f0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 d statements ass
24200 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 ociated with a d
24210 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e atabase .** conn
24220 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 ection that are
24230 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 in need of being
24240 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 reset. This ca
24250 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f n be used,.** fo
24260 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 r example, in di
24270 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 agnostic routine
24280 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 s to search for
24290 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 prepared .** sta
242a0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 tements that are
242b0 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 holding a trans
242c0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a action open..*/.
242d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
242e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
242f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
24300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
24310 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 : Dynamically Ty
24320 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
24330 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
24340 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
24350 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
24360 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
24370 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
24380 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
24390 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
243a0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
243b0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
243c0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
243d0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
243e0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
243f0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
24400 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
24410 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 t stores. ^Valu
24420 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c es stored in sql
24430 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
24440 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 ts.** can be int
24450 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 egers, floating
24460 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 point values, st
24470 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 rings, BLOBs, or
24480 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 NULL..**.** An
24490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
244a0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 ject may be eith
244b0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f er "protected" o
244c0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e r "unprotected".
244d0 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 .** Some interfa
244e0 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 ces require a pr
244f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
24500 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e value. Other in
24510 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c terfaces.** will
24520 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 accept either a
24530 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e protected or an
24540 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
24550 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 ite3_value..** E
24560 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 very interface t
24570 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 hat accepts sqli
24580 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 te3_value argume
24590 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a nts specifies.**
245a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
245b0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 it requires a pr
245c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
245d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
245e0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 terms "protecte
245f0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 d" and "unprotec
24600 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 ted" refer to wh
24610 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 ether or not.**
24620 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e a mutex is held.
24630 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 An internal mu
24640 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
24650 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 a protected.** s
24660 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
24670 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 ect but no mutex
24680 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 is held for an
24690 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
246a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
246b0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 ect. If SQLite
246c0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 is compiled to b
246d0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 e single-threade
246e0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 d.** (with [SQLI
246f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
24700 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 and with [sqlit
24710 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
24720 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a returning 0).**
24730 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 or if SQLite is
24740 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 run in one of r
24750 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 educed mutex mod
24760 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 es .** [SQLITE_C
24770 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
24780 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 AD] or [SQLITE_C
24790 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
247a0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 D].** then there
247b0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 is no distincti
247c0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
247d0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
247e0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
247f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e value objects an
24800 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 d they can be us
24810 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 ed interchangeab
24820 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ly. However,.**
24830 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 for maximum cod
24840 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 e portability it
24850 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
24860 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
24870 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 s.** still make
24880 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 the distinction
24890 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
248a0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
248b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
248c0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 ue objects even
248d0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c when not strictl
248e0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a y required..**.*
248f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
24900 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 alue objects tha
24910 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 t are passed as
24920 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 parameters into
24930 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
24940 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 ation of [applic
24950 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
24960 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 L functions] are
24970 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e protected..** ^
24980 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
24990 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
249a0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
249b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
249c0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
249d0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
249e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
249f0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
24a00 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b e used with.** [
24a10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
24a20 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
24a30 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
24a40 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
24a50 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c te3_value_blob |
24a60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
24a70 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 ype()] family of
24a80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 .** interfaces r
24a90 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 equire protected
24aa0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
24ab0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 bjects..*/.typed
24ac0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 ef struct Mem sq
24ad0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
24ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
24af0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
24b00 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 xt Object.**.**
24b10 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
24b20 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
24b30 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
24b40 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
24b50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
24b60 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
24b70 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
24b80 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
24b90 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
24ba0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
24bb0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
24bc0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
24bd0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
24be0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
24bf0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
24c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
24c10 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
24c20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
24c30 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
24c40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
24c50 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
24c60 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
24c70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
24c80 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
24c90 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
24ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
24cb0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
24cc0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
24cd0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
24ce0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
24cf0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
24d00 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
24d10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
24d20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
24d30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
24d40 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
24d50 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
24d60 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f tements.** KEYWO
24d70 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
24d80 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
24d90 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
24da0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
24db0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
24dc0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
24dd0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
24de0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
24df0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 **.** ^(In the S
24e00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
24e10 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 t input to [sqli
24e20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
24e30 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
24e40 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
24e50 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
24e60 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d by a [parameter]
24e70 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e that matches on
24e80 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a e of following.*
24e90 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a * templates:.**.
24ea0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
24eb0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e ?.** <li> ?NNN
24ec0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a .** <li> :VVV.*
24ed0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 * <li> @VVV.**
24ee0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f <li> $VVV.** </
24ef0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ul>.**.** In the
24f00 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 templates above
24f10 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 , NNN represents
24f20 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 an integer lite
24f30 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 ral,.** and VVV
24f40 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c represents an al
24f50 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 phanumeric ident
24f60 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 ifier.)^ ^The v
24f70 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a alues of these.*
24f80 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c * parameters (al
24f90 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 so called "host
24fa0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 parameter names"
24fb0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 or "SQL paramet
24fc0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 ers").** can be
24fd0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 set using the sq
24fe0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
24ff0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 outines defined
25000 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 here..**.** ^The
25010 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
25020 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 to the sqlite3_b
25030 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
25040 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 is always.** a
25050 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
25060 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
25070 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 ject returned fr
25080 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 om.** [sqlite3_p
25090 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
250a0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a its variants..**
250b0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
250c0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
250d0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c index of the SQL
250e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 parameter to be
250f0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 set..** ^The le
25100 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d ftmost SQL param
25110 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
25120 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 x of 1. ^When t
25130 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a he same named.**
25140 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 SQL parameter i
25150 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e s used more than
25160 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e once, second an
25170 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 d subsequent.**
25180 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 occurrences have
25190 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 the same index
251a0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 as the first occ
251b0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 urrence..** ^The
251c0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
251d0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
251e0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
251f0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
25200 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
25210 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 r_index()] API i
25220 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 f desired. ^The
25230 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f index.** for "?
25240 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 NNN" parameters
25250 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
25260 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e NNN..** ^The NNN
25270 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 value must be b
25280 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 etween 1 and the
25290 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
252a0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 )].** parameter
252b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
252c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 RIABLE_NUMBER] (
252d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 default value: 9
252e0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 99)..**.** ^The
252f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
25300 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 s the value to b
25310 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d ind to the param
25320 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e eter..**.** ^(In
25330 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 those routines
25340 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
25350 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
25360 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
25370 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
25380 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
25390 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
253a0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
253b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c e.** number of <
253c0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 u>bytes</u> in t
253d0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 he value, not th
253e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
253f0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 acters.)^.** ^If
25400 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
25410 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 meter is negativ
25420 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 e, the length of
25430 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a the string is.*
25440 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
25450 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 bytes up to the
25460 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
25470 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e nator..** If a n
25480 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 on-negative four
25490 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
254a0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 provided to sqli
254b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a te3_bind_text().
254c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 ** or sqlite3_bi
254d0 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e nd_text16() then
254e0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 that parameter
254f0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 must be the byte
25500 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 offset.** where
25510 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 the NUL termina
25520 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 tor would occur
25530 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 assuming the str
25540 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 ing were NUL.**
25550 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 terminated. If
25560 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 any NUL characte
25570 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 rs occur at byte
25580 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 offsets less th
25590 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 an .** the value
255a0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 of the fourth p
255b0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 arameter then th
255c0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
255d0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a ng value will.**
255e0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
255f0 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 d NULs. The res
25600 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f ult of expressio
25610 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 ns involving str
25620 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 ings.** with emb
25630 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e edded NULs is un
25640 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
25650 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
25660 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 nt to sqlite3_bi
25670 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 nd_blob(), sqlit
25680 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 e3_bind_text(),
25690 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 and.** sqlite3_b
256a0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 ind_text16() is
256b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 a destructor use
256c0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 d to dispose of
256d0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 the BLOB or.** s
256e0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 tring after SQLi
256f0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 te has finished
25700 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 with it. ^The d
25710 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c estructor is cal
25720 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 led.** to dispos
25730 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
25740 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 string even if
25750 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 the call to sqli
25760 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c te3_bind_blob(),
25770 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 .** sqlite3_bind
25780 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 _text(), or sqli
25790 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
257a0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 ) fails. .** ^I
257b0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
257c0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 ment is.** the s
257d0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 pecial value [SQ
257e0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 LITE_STATIC], th
257f0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 en SQLite assume
25800 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e s that the.** in
25810 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 formation is in
25820 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 static, unmanage
25830 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 d space and does
25840 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
25850 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 freed..** ^If th
25860 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
25870 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b has the value [
25880 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
25890 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 ], then.** SQLit
258a0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 e makes its own
258b0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
258c0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 the data immedia
258d0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 tely, before.**
258e0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
258f0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 _*() routine ret
25900 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
25910 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
25920 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 roblob() routine
25930 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 binds a BLOB of
25940 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a length N that.*
25950 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 * is filled with
25960 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 zeroes. ^A zer
25970 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 oblob uses a fix
25980 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d ed amount of mem
25990 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 ory.** (just an
259a0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 integer to hold
259b0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 its size) while
259c0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 it is being proc
259d0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c essed..** Zerobl
259e0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 obs are intended
259f0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 to serve as pla
25a00 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c ceholders for BL
25a10 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e OBs whose.** con
25a20 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 tent is later wr
25a30 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b itten using.** [
25a40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
25a50 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 n | incremental
25a60 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e BLOB I/O] routin
25a70 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 es..** ^A negati
25a80 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
25a90 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
25aa0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
25ab0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e th BLOB..**.** ^
25ac0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 If any of the sq
25ad0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
25ae0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
25af0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
25b00 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 ointer.** for th
25b10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
25b20 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 ement] or with a
25b30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
25b40 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a ent for which.**
25b50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
25b60 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 ] has been calle
25b70 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 d more recently
25b80 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 than [sqlite3_re
25b90 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 set()],.** then
25ba0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 the call will re
25bb0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 turn [SQLITE_MIS
25bc0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 USE]. If any sq
25bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a lite3_bind_().**
25be0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 routine is pass
25bf0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 ed a [prepared s
25c00 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
25c10 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
25c20 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 d, the.** result
25c30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
25c40 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 d probably harmf
25c50 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 ul..**.** ^Bindi
25c60 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 ngs are not clea
25c70 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 red by the [sqli
25c80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 te3_reset()] rou
25c90 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e tine..** ^Unboun
25ca0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 d parameters are
25cb0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
25cc0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
25cd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 sqlite3_bind_*
25ce0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
25cf0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
25d00 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 uccess or an.**
25d10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
25d20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 anything goes wr
25d30 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ong..** ^[SQLITE
25d40 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 _RANGE] is retur
25d50 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d ned if the param
25d60 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 eter.** index is
25d70 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 out of range.
25d80 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 ^[SQLITE_NOMEM]
25d90 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
25da0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a alloc() fails..*
25db0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
25dc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
25dd0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
25de0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
25df0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
25e00 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
25e10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
25e20 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
25e30 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
25e40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 ite3_bind_blob(s
25e50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
25e60 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
25e70 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
25e80 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
25e90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
25ea0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ind_double(sqlit
25eb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 e3_stmt*, int, d
25ec0 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 ouble);.SQLITE_A
25ed0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
25ee0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f ind_int(sqlite3_
25ef0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 stmt*, int, int)
25f00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
25f10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
25f20 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
25f30 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
25f40 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 int64);.SQLITE_A
25f50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
25f60 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ind_null(sqlite3
25f70 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 _stmt*, int);.SQ
25f80 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
25f90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
25fa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
25fb0 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 t, const char*,
25fc0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
25fd0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
25fe0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
25ff0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ind_text16(sqlit
26000 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
26010 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
26020 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
26030 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
26040 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
26050 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
26060 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
26070 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
26080 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
26090 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
260a0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
260b0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a *, int, int n);.
260c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
260d0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 Number Of SQL P
260e0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 arameters.**.**
260f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 ^This routine ca
26100 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e n be used to fin
26110 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
26120 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d [SQL parameters]
26130 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 .** in a [prepar
26140 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
26150 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 SQL parameters a
26160 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 re tokens of the
26170 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f .** form "?", "?
26180 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 NNN", ":AAA", "$
26190 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 AAA", or "@AAA"
261a0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a that serve as.**
261b0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
261c0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 r values that ar
261d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
261e0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a blob | bound].**
261f0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
26200 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 rs at a later ti
26210 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 me..**.** ^(This
26220 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c routine actuall
26230 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e y returns the in
26240 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 dex of the large
26250 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a st (rightmost).*
26260 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 * parameter. For
26270 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 all forms excep
26280 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c t ?NNN, this wil
26290 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 l correspond to
262a0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
262b0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 unique paramete
262c0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 rs. If paramete
262d0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 rs of the ?NNN f
262e0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a orm are used,.**
262f0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 there may be ga
26300 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 ps in the list.)
26310 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
26320 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
26330 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
26340 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
26350 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
26360 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a _name()], and.**
26370 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
26380 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
26390 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
263a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
263b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
263c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
263d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
263e0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
263f0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a t Parameter.**.*
26400 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
26410 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
26420 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(P,N) interfac
26430 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 e returns.** the
26440 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 name of the N-t
26450 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 h [SQL parameter
26460 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 ] in the [prepar
26470 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
26480 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 .** ^(SQL parame
26490 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
264a0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
264b0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
264c0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
264d0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
264e0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
264f0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
26500 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
26510 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
26520 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
26530 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
26540 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
26550 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
26560 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
26570 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 the name.)^.**
26580 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 ^Parameters of t
26590 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
265a0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
265b0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
265c0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
265d0 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 referred to as "
265e0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e nameless" or "an
265f0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
26600 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rs"..**.** ^The
26610 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
26620 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
26630 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
26640 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c *.** ^If the val
26650 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 ue N is out of r
26660 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e ange or if the N
26670 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 -th parameter is
26680 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 .** nameless, th
26690 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 en NULL is retur
266a0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ned. ^The retur
266b0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a ned string is.**
266c0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 always in UTF-8
266d0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 encoding even i
266e0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 f the named para
266f0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 meter was.** ori
26700 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 ginally specifie
26710 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b d as UTF-16 in [
26720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
26730 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 6()] or.** [sqli
26740 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
26750 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
26760 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
26770 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
26780 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
26790 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
267a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
267b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
267c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
267d0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ex()]..*/.SQLITE
267e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
267f0 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 *sqlite3_bind_pa
26800 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c rameter_name(sql
26810 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
26820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
26830 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 F: Index Of A Pa
26840 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 rameter With A G
26850 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 iven Name.**.**
26860 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 ^Return the inde
26870 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 x of an SQL para
26880 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 meter given its
26890 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 name. ^The.** i
268a0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
268b0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
268c0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
268d0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
268e0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
268f0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
26900 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 _bind()]. ^A ze
26910 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 ro.** is returne
26920 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 d if no matching
26930 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f parameter is fo
26940 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d und. ^The param
26950 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 eter.** name mus
26960 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 t be given in UT
26970 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 F-8 even if the
26980 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
26990 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 nt.** was prepar
269a0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 ed from UTF-16 t
269b0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ext using [sqlit
269c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
269d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
269e0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
269f0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
26a00 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
26a10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
26a20 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
26a30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
26a40 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
26a50 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f x()]..*/.SQLITE_
26a60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
26a70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
26a80 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d ndex(sqlite3_stm
26a90 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a t*, const char *
26aa0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 zName);../*.** C
26ab0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
26ac0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 ll Bindings On A
26ad0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
26ae0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 ent.**.** ^Contr
26af0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 ary to the intui
26b00 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 tion of many, [s
26b10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
26b20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a does not reset.*
26b30 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * the [sqlite3_b
26b40 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 ind_blob | bindi
26b50 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 ngs] on a [prepa
26b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
26b70 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 ** ^Use this rou
26b80 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c tine to reset al
26b90 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 l host parameter
26ba0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 s to NULL..*/.SQ
26bb0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
26bc0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
26bd0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
26be0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
26bf0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 REF: Number Of C
26c00 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 olumns In A Resu
26c10 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 lt Set.**.** ^Re
26c20 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 turn the number
26c30 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
26c40 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 e result set ret
26c50 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 urned by the.**
26c60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26c70 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 ent]. ^This rout
26c80 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 ine returns 0 if
26c90 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c pStmt is an SQL
26ca0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 .** statement th
26cb0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 at does not retu
26cc0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 rn data (for exa
26cd0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d mple an [UPDATE]
26ce0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )..**.** See als
26cf0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 o: [sqlite3_data
26d00 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c _count()].*/.SQL
26d10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
26d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
26d30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
26d40 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
26d50 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e PI3REF: Column N
26d60 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 ames In A Result
26d70 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 Set.**.** ^Thes
26d80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
26d90 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 n the name assig
26da0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 ned to a particu
26db0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e lar column.** in
26dc0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
26dd0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 of a [SELECT] st
26de0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 atement. ^The s
26df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
26e00 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 me().** interfac
26e10 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
26e20 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 ter to a zero-te
26e30 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
26e40 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c tring.** and sql
26e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
26e60 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 16() returns a p
26e70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f ointer to a zero
26e80 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
26e90 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
26ea0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
26eb0 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 ter is the [prep
26ec0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
26ed0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ** that implemen
26ee0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 ts the [SELECT]
26ef0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 statement. ^The
26f00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
26f10 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d is the.** colum
26f20 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 n number. ^The
26f30 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 leftmost column
26f40 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a is number 0..**.
26f50 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
26f60 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 string pointer
26f70 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 is valid until e
26f80 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 ither the [prepa
26f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
26fa0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 * is destroyed b
26fb0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c y [sqlite3_final
26fc0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
26fd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
26fe0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
26ff0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 * reprepared by
27000 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 the first call t
27010 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
27020 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 )] for a particu
27030 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e lar run.** or un
27040 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c til the next cal
27050 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
27060 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 column_name() or
27070 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
27080 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 name16() on the
27090 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a same column..**.
270a0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d ** ^If sqlite3_m
270b0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 alloc() fails du
270c0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 ring the process
270d0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f ing of either ro
270e0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 utine.** (for ex
270f0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 ample during a c
27100 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 onversion from U
27110 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 TF-8 to UTF-16)
27120 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 then a.** NULL p
27130 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
27140 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e ed..**.** ^The n
27150 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 ame of a result
27160 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 column is the va
27170 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 lue of the "AS"
27180 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 clause for.** th
27190 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 at column, if th
271a0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 ere is an AS cla
271b0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 use. If there i
271c0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a s no AS clause.*
271d0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 * then the name
271e0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 of the column is
271f0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 unspecified and
27200 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d may change from
27210 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 .** one release
27220 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 of SQLite to the
27230 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 next..*/.SQLITE
27240 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
27250 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
27260 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
27270 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 t*, int N);.SQLI
27280 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
27290 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
272a0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
272b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
272c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
272d0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 Source Of Data
272e0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c In A Query Resul
272f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 t.**.** ^These r
27300 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 outines provide
27310 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 a means to deter
27320 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 mine the databas
27330 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a e, table, and.**
27340 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
27350 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e at is the origin
27360 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 of a particular
27370 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
27380 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 n.** [SELECT] st
27390 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 atement..** ^The
273a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
273b0 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f abase or table o
273c0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 r column can be
273d0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 returned as.** e
273e0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 ither a UTF-8 or
273f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 UTF-16 string.
27400 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f ^The _database_
27410 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
27420 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
27430 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c name, the _tabl
27440 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
27450 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d rn the table nam
27460 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 e, and.** the or
27470 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 igin_ routines r
27480 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e eturn the column
27490 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 name..** ^The r
274a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
274b0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 s valid until th
274c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
274d0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f ement] is destro
274e0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 yed.** using [sq
274f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
27500 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 ] or until the s
27510 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f tatement is auto
27520 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 matically.** rep
27530 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 repared by the f
27540 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 irst call to [sq
27550 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f lite3_step()] fo
27560 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 r a particular r
27570 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 un.** or until t
27580 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
27590 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 ion is requested
275a0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 .** again in a d
275b0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e ifferent encodin
275c0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 g..**.** ^The na
275d0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 mes returned are
275e0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e the original un
275f0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f -aliased names o
27600 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 f the.** databas
27610 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f e, table, and co
27620 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lumn..**.** ^The
27630 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
27640 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
27650 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 ces is a [prepar
27660 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
27670 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f * ^These functio
27680 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d ns return inform
27690 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 ation about the
276a0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d Nth result colum
276b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a n returned by.**
276c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 the statement,
276d0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
276e0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 econd function a
276f0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 rgument..** ^The
27700 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d left-most colum
27710 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f n is column 0 fo
27720 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 r these routines
27730 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
27740 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
27750 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 ned by the state
27760 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 ment is an expre
27770 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 ssion or.** subq
27780 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 uery and is not
27790 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 a column value,
277a0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 then all of thes
277b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
277c0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 rn.** NULL. ^Th
277d0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 ese routine migh
277e0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 t also return NU
277f0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 LL if a memory a
27800 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a llocation error.
27810 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 ** occurs. ^Oth
27820 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
27830 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
27840 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
27850 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a abase, table,.**
27860 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 or column that
27870 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
27880 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
27890 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 d from..**.** ^A
278a0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 s with all other
278b0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 SQLite APIs, th
278c0 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 ose whose names
278d0 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 end with "16" re
278e0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 turn.** UTF-16 e
278f0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 ncoded strings a
27900 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e nd the other fun
27910 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 ctions return UT
27920 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 F-8..**.** ^Thes
27930 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 e APIs are only
27940 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
27950 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
27960 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
27970 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
27980 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
27990 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C-preprocessor
279a0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 symbol..**.** I
279b0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 f two or more th
279c0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f reads call one o
279d0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 r more of these
279e0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 routines against
279f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 the same.** pre
27a00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
27a10 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 and column at th
27a20 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
27a30 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
27a40 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
27a50 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d *.** If two or m
27a60 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c ore threads call
27a70 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
27a80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
27a90 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 database_name |
27aa0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 column metadata
27ab0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 interfaces].** f
27ac0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 or the same [pre
27ad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27ae0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 and result colu
27af0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d mn.** at the sam
27b00 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
27b10 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
27b20 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fined..*/.SQLITE
27b30 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
27b40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
27b50 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 database_name(sq
27b60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
27b70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
27b80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
27b90 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
27ba0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
27bb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
27bc0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
27bd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
27be0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c n_table_name(sql
27bf0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
27c00 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
27c10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
27c20 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
27c30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
27c40 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
27c50 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
27c60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
27c70 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 igin_name(sqlite
27c80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
27c90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
27ca0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
27cb0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 umn_origin_name1
27cc0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
27cd0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
27ce0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 I3REF: Declared
27cf0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 Datatype Of A Qu
27d00 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a ery Result.**.**
27d10 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 ^(The first par
27d20 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 ameter is a [pre
27d30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27d40 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 ..** If this sta
27d50 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c tement is a [SEL
27d60 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ECT] statement a
27d70 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d nd the Nth colum
27d80 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 n of the.** retu
27d90 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 rned result set
27da0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d of that [SELECT]
27db0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 is a table colu
27dc0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 mn (not an.** ex
27dd0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
27de0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 uery) then the d
27df0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 eclared type of
27e00 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c the table.** col
27e10 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e umn is returned.
27e20 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 )^ ^If the Nth
27e30 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
27e40 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a sult set is an.*
27e50 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
27e60 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 subquery, then a
27e70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
27e80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 returned..** ^T
27e90 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
27ea0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 ng is always UTF
27eb0 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a -8 encoded..**.*
27ec0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c * ^(For example,
27ed0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 given the datab
27ee0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a ase schema:.**.*
27ef0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 * CREATE TABLE t
27f00 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 1(c1 VARIANT);.*
27f10 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c *.** and the fol
27f20 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 lowing statement
27f30 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a to be compiled:
27f40 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 .**.** SELECT c1
27f50 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 + 1, c1 FROM t1
27f60 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ;.**.** this rou
27f70 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 tine would retur
27f80 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 n the string "VA
27f90 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 RIANT" for the s
27fa0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 econd result.**
27fb0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 column (i==1), a
27fc0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nd a NULL pointe
27fd0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 r for the first
27fe0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 result column (i
27ff0 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 ==0).)^.**.** ^S
28000 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
28010 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
28020 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 ng. ^So just be
28030 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a cause a column.*
28040 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f * is declared to
28050 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 contain a parti
28060 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 cular type does
28070 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 not mean that th
28080 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 e.** data stored
28090 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 in that column
280a0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 is of the declar
280b0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 ed type. SQLite
280c0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 is.** strongly
280d0 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 typed, but the t
280e0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 yping is dynamic
280f0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 not static. ^T
28100 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 ype.** is associ
28110 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 ated with indivi
28120 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 dual values, not
28130 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 with the contai
28140 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ners.** used to
28150 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 hold those value
28160 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
28170 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
28180 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
28190 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
281a0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
281b0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
281c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
281d0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 ecltype16(sqlite
281e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
281f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
28200 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 valuate An SQL S
28210 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 tatement.**.** A
28220 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 fter a [prepared
28230 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 statement] has
28240 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 been prepared us
28250 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 ing either.** [s
28260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
28270 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
28280 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
28290 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c or one of the l
282a0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
282b0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
282c0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 pare()] or [sqli
282d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
282e0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a , this function.
282f0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ** must be calle
28300 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
28310 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 mes to evaluate
28320 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a the statement..*
28330 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 *.** The details
28340 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 of the behavior
28350 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
28360 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 step() interface
28370 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 depend.** on wh
28380 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d ether the statem
28390 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 ent was prepared
283a0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 using the newer
283b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a "v2" interface.
283c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
283d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
283e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
283f0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c _v2()] or the ol
28400 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e der legacy.** in
28410 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 terface [sqlite3
28420 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
28430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28440 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 16()]. The use
28450 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 of the.** new "v
28460 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
28470 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
28480 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
28490 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a but the legacy.
284a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c ** interface wil
284b0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 l continue to be
284c0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a supported..**.*
284d0 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 * ^In the legacy
284e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
284f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c return value wil
28500 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c l be either [SQL
28510 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 ITE_BUSY],.** [S
28520 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 QLITE_DONE], [SQ
28530 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 LITE_ROW], [SQLI
28540 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 TE_ERROR], or [S
28550 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a QLITE_MISUSE]..*
28560 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 * ^With the "v2"
28570 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 interface, any
28580 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 of the other [re
28590 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a sult codes] or.*
285a0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
285b0 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 lt codes] might
285c0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 be returned as w
285d0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c ell..**.** ^[SQL
285e0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 ITE_BUSY] means
285f0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 that the databas
28600 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 e engine was una
28610 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 ble to acquire t
28620 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c he.** database l
28630 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f ocks it needs to
28640 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 do its job. ^I
28650 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
28660 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a is a [COMMIT].**
28670 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 or occurs outsi
28680 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 de of an explici
28690 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
286a0 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 hen you can retr
286b0 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 y the.** stateme
286c0 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 nt. If the stat
286d0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b ement is not a [
286e0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 COMMIT] and occu
286f0 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 rs within an.**
28700 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 explicit transac
28710 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 tion then you sh
28720 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 ould rollback th
28730 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 e transaction be
28740 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 fore.** continui
28750 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ng..**.** ^[SQLI
28760 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 TE_DONE] means t
28770 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e hat the statemen
28780 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 t has finished e
28790 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 xecuting.** succ
287a0 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 essfully. sqlit
287b0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 e3_step() should
287c0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 not be called a
287d0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 gain on this vir
287e0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
287f0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 without first ca
28800 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
28810 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 eset()] to reset
28820 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 the virtual.**
28830 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 machine back to
28840 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 its initial stat
28850 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 e..**.** ^If the
28860 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 SQL statement b
28870 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 eing executed re
28880 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 turns any data,
28890 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 then [SQLITE_ROW
288a0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 ].** is returned
288b0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 each time a new
288c0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 row of data is
288d0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 ready for proces
288e0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 sing by the.** c
288f0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 aller. The value
28900 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 s may be accesse
28910 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c d using the [col
28920 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
28930 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 ions]..** sqlite
28940 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 3_step() is call
28950 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 ed again to retr
28960 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f ieve the next ro
28970 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a w of data..**.**
28980 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d ^[SQLITE_ERROR]
28990 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 means that a ru
289a0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 n-time error (su
289b0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 ch as a constrai
289c0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 nt.** violation)
289d0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 has occurred.
289e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
289f0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
28a00 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 led again on.**
28a10 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 the VM. More inf
28a20 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 ormation may be
28a30 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 found by calling
28a40 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
28a50 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 ()]..** ^With th
28a60 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
28a70 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 ce, a more speci
28a80 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 fic error code (
28a90 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 for example,.**
28aa0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
28ab0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 T], [SQLITE_SCHE
28ac0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 MA], [SQLITE_COR
28ad0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f RUPT], and so fo
28ae0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f rth).** can be o
28af0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 btained by calli
28b00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
28b10 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b t()] on the.** [
28b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28b30 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 nt]. ^In the "v
28b40 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 2" interface,.**
28b50 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
28b60 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ic error code is
28b70 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
28b80 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ly by sqlite3_st
28b90 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c ep()..**.** [SQL
28ba0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e ITE_MISUSE] mean
28bb0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 s that the this
28bc0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c routine was call
28bd0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 ed inappropriate
28be0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 ly..** Perhaps i
28bf0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 t was called on
28c00 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
28c10 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a ement] that has.
28c20 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 ** already been
28c30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
28c40 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f e | finalized] o
28c50 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 r on one that ha
28c60 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 d.** previously
28c70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
28c80 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 _ERROR] or [SQLI
28c90 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 TE_DONE]. Or it
28ca0 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 could.** be the
28cb0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 case that the s
28cc0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
28cd0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 nection is being
28ce0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a used by two or.
28cf0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 ** more threads
28d00 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 at the same mome
28d10 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a nt in time..**.*
28d20 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f * For all versio
28d30 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 ns of SQLite up
28d40 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 to and including
28d50 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 3.6.23.1, a cal
28d60 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
28d70 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 _reset()] was re
28d80 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c quired after sql
28d90 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 ite3_step() retu
28da0 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a rned anything.**
28db0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
28dc0 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 ITE_ROW] before
28dd0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 any subsequent i
28de0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 nvocation of.**
28df0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
28e00 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 Failure to rese
28e10 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
28e20 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a tatement using .
28e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
28e40 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c t()] would resul
28e50 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f t in an [SQLITE_
28e60 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 MISUSE] return f
28e70 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 rom.** sqlite3_s
28e80 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 tep(). But afte
28e90 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 r version 3.6.23
28ea0 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .1, sqlite3_step
28eb0 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c () began.** call
28ec0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
28ed0 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 et()] automatica
28ee0 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 lly in this circ
28ef0 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a umstance rather.
28f00 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e ** than returnin
28f10 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 g [SQLITE_MISUSE
28f20 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 ]. This is not
28f30 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d considered a com
28f40 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 patibility.** br
28f50 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 eak because any
28f60 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 application that
28f70 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 ever receives a
28f80 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 n SQLITE_MISUSE
28f90 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b error.** is brok
28fa0 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e en by definition
28fb0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f . The [SQLITE_O
28fc0 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 MIT_AUTORESET] c
28fd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
28fe0 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 on.** can be use
28ff0 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 d to restore the
29000 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
29010 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 ..**.** <b>Goofy
29020 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 Interface Alert
29030 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 :</b> In the leg
29040 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
29050 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 he sqlite3_step(
29060 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 ).** API always
29070 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 returns a generi
29080 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 c error code, [S
29090 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f QLITE_ERROR], fo
290a0 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 llowing any.** e
290b0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 rror other than
290c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e [SQLITE_BUSY] an
290d0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 d [SQLITE_MISUSE
290e0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c ]. You must cal
290f0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 l.** [sqlite3_re
29100 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
29110 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
29120 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 n order to find
29130 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 one of the.** sp
29140 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f ecific [error co
29150 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 des] that better
29160 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
29170 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 rror..** We admi
29180 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 t that this is a
29190 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 goofy design.
291a0 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 The problem has
291b0 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 been fixed.** wi
291c0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
291d0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 rface. If you p
291e0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f repare all of yo
291f0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ur SQL statement
29200 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 s.** using eithe
29210 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
29220 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
29230 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
29240 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 2()] instead.**
29250 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 of the legacy [s
29260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
29270 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
29280 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 repare16()] inte
29290 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 rfaces,.** then
292a0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
292b0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 c [error codes]
292c0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 are returned dir
292d0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 ectly.** by sqli
292e0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 te3_step(). The
292f0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 use of the "v2"
29300 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
29310 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 commended..*/.SQ
29320 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
29330 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 ite3_step(sqlite
29340 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
29350 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
29360 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
29370 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a a result set.**.
29380 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
29390 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e data_count(P) in
293a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
293b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
293c0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 lumns in the.**
293d0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 current row of t
293e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
293f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29400 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 ment] P..** ^If
29410 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29420 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 nt P does not ha
29430 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 ve results ready
29440 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 to return.** (v
29450 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 ia calls to the
29460 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
29470 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f int | sqlite3_co
29480 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 lumn_*()] of.**
29490 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e interfaces) then
294a0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
294b0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 unt(P) returns 0
294c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
294d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
294e0 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 routine also ret
294f0 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 urns 0 if P is a
29500 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
29510 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
29520 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 ata_count(P) rou
29530 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 tine returns 0 i
29540 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 f the previous c
29550 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
29560 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 e3_step](P) retu
29570 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e rned [SQLITE_DON
29580 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 E]. ^The sqlite
29590 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 3_data_count(P).
295a0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e ** will return n
295b0 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 on-zero if previ
295c0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ous call to [sql
295d0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 ite3_step](P) re
295e0 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 turned.** [SQLIT
295f0 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 E_ROW], except i
29600 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 n the case of th
29610 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d e [PRAGMA increm
29620 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a ental_vacuum].**
29630 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 where it always
29640 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 returns zero si
29650 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 nce each step of
29660 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 that multi-step
29670 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 .** pragma retur
29680 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 ns 0 columns of
29690 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 data..**.** See
296a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 also: [sqlite3_c
296b0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a olumn_count()].*
296c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
296d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
296e0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
296f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
29700 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
29710 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
29720 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
29730 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
29740 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
29750 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
29760 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
29770 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
29780 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
29790 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
297a0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
297b0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
297c0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
297d0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
297e0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
297f0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
29800 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
29810 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
29820 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
29830 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
29840 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
29850 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
29860 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
29870 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
29880 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
29890 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
298a0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
298b0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
298c0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
298d0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
298e0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
298f0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
29900 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
29910 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
29920 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
29930 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
29940 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
29950 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
29960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
29970 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
29980 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
29990 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
299a0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
299b0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
299c0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
299d0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
299e0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
299f0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
29a00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
29a10 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
29a20 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
29a30 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
29a40 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
29a50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
29a60 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
29a70 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 result set" inte
29a80 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rface..**.** ^Th
29a90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
29aa0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
29ab0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
29ac0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
29ad0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
29ae0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
29af0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
29b00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
29b10 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
29b20 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
29b30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
29b40 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
29b50 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
29b60 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
29b70 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
29b80 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
29b90 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
29ba0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
29bb0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
29bc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
29bd0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
29be0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
29bf0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
29c00 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
29c10 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
29c20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
29c30 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
29c40 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
29c50 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
29c60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
29c70 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
29c80 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
29c90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
29ca0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
29cb0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
29cc0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
29cd0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
29ce0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
29cf0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
29d00 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
29d10 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
29d20 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
29d30 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
29d40 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
29d50 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
29d60 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
29d70 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
29d80 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
29d90 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
29da0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
29db0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
29dc0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
29dd0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
29de0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
29df0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
29e00 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
29e10 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
29e20 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
29e30 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
29e40 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
29e50 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
29e60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
29e70 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
29e80 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
29e90 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
29ea0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
29eb0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
29ec0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
29ed0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
29ee0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
29ef0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
29f00 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
29f10 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
29f20 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
29f30 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
29f40 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
29f50 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
29f60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
29f70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
29f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
29f90 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
29fa0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
29fb0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
29fc0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
29fd0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
29fe0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
29ff0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
2a000 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2a010 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
2a020 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
2a030 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
2a040 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
2a050 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
2a060 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
2a070 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
2a080 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2a090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2a0a0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
2a0b0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
2a0c0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
2a0d0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
2a0e0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
2a0f0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
2a100 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
2a110 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2a120 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2a130 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2a140 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
2a150 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
2a160 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
2a170 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
2a180 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
2a190 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
2a1a0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
2a1b0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
2a1c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2a1d0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2a1e0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2a1f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2a200 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2a210 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2a220 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2a230 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2a240 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2a250 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2a260 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
2a270 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2a280 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
2a290 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2a2a0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
2a2b0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
2a2c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
2a2d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2a2e0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
2a2f0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
2a300 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2a310 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2a320 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2a330 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2a340 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
2a350 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2a360 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2a370 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2a380 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2a390 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2a3a0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2a3b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2a3c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2a3d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2a3e0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2a3f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
2a400 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2a410 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
2a420 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
2a430 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2a440 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
2a450 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
2a460 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2a470 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
2a480 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
2a490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2a4a0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2a4b0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2a4c0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
2a4d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2a4e0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2a4f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2a500 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2a510 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2a520 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
2a530 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2a540 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2a550 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2a560 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
2a570 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2a580 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2a590 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2a5a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2a5b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2a5c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2a5d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
2a5e0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2a5f0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
2a600 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2a610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2a620 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
2a630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2a640 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
2a650 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
2a660 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
2a670 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
2a680 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
2a690 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
2a6a0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2a6b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2a6c0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
2a6d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2a6e0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
2a6f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2a700 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2a710 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2a720 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2a730 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
2a740 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2a750 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2a760 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2a770 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
2a780 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
2a790 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
2a7a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
2a7b0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
2a7c0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
2a7d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2a7e0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
2a7f0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
2a800 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2a810 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 * ^The object re
2a820 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2a830 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2a840 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
2a850 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2a860 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
2a870 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
2a880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2a890 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
2a8a0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
2a8b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2a8c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2a8d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2a8e0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
2a8f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2a900 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2a910 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
2a920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2a930 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
2a940 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
2a950 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
2a960 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
2a970 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
2a980 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
2a990 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2a9a0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
2a9b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2a9c0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
2a9d0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2a9e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
2a9f0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
2aa00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
2aa10 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
2aa20 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a opriate. ^For.*
2aa30 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
2aa40 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
2aa50 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
2aa60 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
2aa70 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
2aa80 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
2aa90 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
2aaa0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
2aab0 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
2aac0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
2aad0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 atically. ^(The
2aae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
2aaf0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
2ab00 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
2ab10 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
2ab20 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2ab30 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
2ab40 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
2ab50 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
2ab60 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
2ab70 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
2ab80 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
2ab90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2aba0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2abb0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2abc0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
2abd0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
2abe0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
2abf0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
2ac00 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2ac10 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
2ac20 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
2ac30 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
2ac40 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2ac50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
2ac60 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
2ac70 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
2ac80 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
2ac90 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2aca0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
2acb0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 integer to floa
2acc0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e t.** <tr><td> IN
2acd0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 TEGER <td> TE
2ace0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
2acf0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
2ad00 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 e integer.** <tr
2ad10 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
2ad20 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
2ad30 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 d> Same as INTEG
2ad40 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e ER->TEXT.** <tr>
2ad50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
2ad60 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
2ad70 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 > Convert from f
2ad80 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a loat to integer.
2ad90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
2ada0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 AT <td> TEXT
2adb0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
2adc0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
2add0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2ade0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
2adf0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
2ae00 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 ame as FLOAT->TE
2ae10 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
2ae20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 TEXT <td> INT
2ae30 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 EGER <td> Use
2ae40 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
2ae50 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2ae60 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2ae70 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 Use atof().** <t
2ae80 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2ae90 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
2aea0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a td> No change.**
2aeb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
2aec0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
2aed0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 <td> Convert t
2aee0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 o TEXT then use
2aef0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
2af00 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
2af10 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2af20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 Convert to TEXT
2af30 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a then use atof().
2af40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
2af50 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 B <td> TEXT
2af60 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a <td> Add a z
2af70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
2af80 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 f needed.** </ta
2af90 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 ble>.** </blockq
2afa0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 uote>)^.**.** Th
2afb0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 e table above ma
2afc0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f kes reference to
2afd0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
2afe0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 ary functions at
2aff0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 oi().** and atof
2b000 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 (). SQLite does
2b010 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 not really use
2b020 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
2b030 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 It has its.**
2b040 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 own equivalent i
2b050 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 nternal routines
2b060 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e . The atoi() an
2b070 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 d atof() names a
2b080 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 re.** used in th
2b090 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 e table for brev
2b0a0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 ity and because
2b0b0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 they are familia
2b0c0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 r to most.** C p
2b0d0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a rogrammers..**.*
2b0e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e * Note that when
2b0f0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2b100 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 s occur, pointer
2b110 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 s returned by pr
2b120 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ior.** calls to
2b130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2b140 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 lob(), sqlite3_c
2b150 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e olumn_text(), an
2b160 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d/or.** sqlite3_
2b170 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
2b180 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 may be invalidat
2b190 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 ed..** Type conv
2b1a0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e ersions and poin
2b1b0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e ter invalidation
2b1c0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a s might occur.**
2b1d0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e in the followin
2b1e0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c g cases:.**.** <
2b1f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
2b200 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2b210 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 is a BLOB and sq
2b220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2b230 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 t() or.** s
2b240 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2b250 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
2b260 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e . A zero-termin
2b270 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 ator might.**
2b280 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 need to be ad
2b290 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e ded to the strin
2b2a0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 g.</li>.** <li>
2b2b0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2b2c0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 ent is UTF-8 tex
2b2d0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
2b2e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f lumn_bytes16() o
2b2f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
2b300 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2b310 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
2b320 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
2b330 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
2b340 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f to UTF-16.</
2b350 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
2b360 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2b370 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 is UTF-16 text a
2b380 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2b390 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
2b3a0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
2b3b0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 umn_text() is ca
2b3c0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
2b3d0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
2b3e0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
2b3f0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c UTF-8.</li>.** <
2b400 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 /ul>.**.** ^Conv
2b410 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
2b420 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
2b430 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
2b440 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
2b450 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
2b460 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
2b470 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
2b480 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
2b490 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
2b4a0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
2b4b0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 prior pointer re
2b4c0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 ferences will ha
2b4d0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
2b4e0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
2b4f0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
2b500 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
2b510 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
2b520 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
2b530 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
2b540 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
2b550 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
2b560 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
2b570 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
2b580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
2b590 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f t and easiest to
2b5a0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 remember policy
2b5b0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 is to invoke th
2b5c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
2b5d0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f in one of the fo
2b5e0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a llowing ways:.**
2b5f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 .** <ul>.** <li
2b600 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2b610 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
2b620 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2b630 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
2b640 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
2b650 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
2b660 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
2b670 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
2b680 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
2b690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2b6a0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
2b6b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2b6c0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
2b6d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
2b6e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f other words, yo
2b6f0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 u should call sq
2b700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2b710 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t(),.** sqlite3_
2b720 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f column_blob(), o
2b730 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2b740 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 _text16() first
2b750 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 to force the res
2b760 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ult.** into the
2b770 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 desired format,
2b780 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 then invoke sqli
2b790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2b7a0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
2b7b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2b7c0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 ) to find the si
2b7d0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ze of the result
2b7e0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 . Do not mix ca
2b7f0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 lls.** to sqlite
2b800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
2b810 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
2b820 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
2b830 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
2b840 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2b850 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d (), and do not m
2b860 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ix calls to sqli
2b870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2b880 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 6().** with call
2b890 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
2b8a0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a umn_bytes()..**.
2b8b0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 ** ^The pointers
2b8c0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 returned are va
2b8d0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 lid until a type
2b8e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
2b8f0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 rs as.** describ
2b900 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 ed above, or unt
2b910 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 il [sqlite3_step
2b920 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2b930 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
2b940 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2b950 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 ()] is called.
2b960 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 ^The memory spac
2b970 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 e used to hold s
2b980 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c trings.** and BL
2b990 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 OBs is freed aut
2b9a0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 omatically. Do
2b9b0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 <b>not</b> pass
2b9c0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 the pointers ret
2b9d0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 urned.** [sqlite
2b9e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 3_column_blob()]
2b9f0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d , [sqlite3_colum
2ba00 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 n_text()], etc.
2ba10 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 into.** [sqlite3
2ba20 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _free()]..**.**
2ba30 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c ^(If a memory al
2ba40 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f location error o
2ba50 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 ccurs during the
2ba60 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 evaluation of a
2ba70 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 ny.** of these r
2ba80 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 outines, a defau
2ba90 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 lt value is retu
2baa0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 rned. The defau
2bab0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 lt value.** is e
2bac0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 ither the intege
2bad0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e r 0, the floatin
2bae0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 g point number 0
2baf0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a .0, or a NULL.**
2bb00 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 pointer. Subse
2bb10 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
2bb20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
2bb30 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a )] will return.*
2bb40 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
2bb50 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 .)^.*/.SQLITE_AP
2bb60 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2bb70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2bb80 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
2bb90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
2bba0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2bbb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2bbc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2bbd0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
2bbe0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2bbf0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2bc00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2bc10 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
2bc20 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 _API double sqli
2bc30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c te3_column_doubl
2bc40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2bc50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
2bc60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2bc70 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 e3_column_int(sq
2bc80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2bc90 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
2bca0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
2bcb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2bcc0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
2bcd0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2bce0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2bcf0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
2bd00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2bd10 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
2bd20 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
2bd30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
2bd40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
2bd50 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 umn_text16(sqlit
2bd60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2bd70 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
2bd80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2bd90 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f mn_type(sqlite3_
2bda0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2bdb0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
2bdc0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 ite3_value *sqli
2bdd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
2bde0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2bdf0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a int iCol);../*.*
2be00 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 * CAPI3REF: Dest
2be10 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 roy A Prepared S
2be20 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
2be30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2be40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
2be50 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
2be60 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 to delete a [pr
2be70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2be80 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f ]..** ^If the mo
2be90 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 st recent evalua
2bea0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 tion of the stat
2beb0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 ement encountere
2bec0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f d no errors.** o
2bed0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 r if the stateme
2bee0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e nt is never been
2bef0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e evaluated, then
2bf00 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2bf10 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 e() returns.** S
2bf20 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 QLITE_OK. ^If t
2bf30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
2bf40 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 valuation of sta
2bf50 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c tement S failed,
2bf60 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
2bf70 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 _finalize(S) ret
2bf80 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 urns the appropr
2bf90 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
2bfa0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
2bfb0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a d error code]..*
2bfc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2bfd0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 3_finalize(S) ro
2bfe0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c utine can be cal
2bff0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 led at any point
2c000 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c during.** the l
2c010 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 ife cycle of [pr
2c020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c030 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 ] S:.** before s
2c040 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 tatement S is ev
2c050 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 er evaluated, af
2c060 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f ter.** one or mo
2c070 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c re calls to [sql
2c080 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f ite3_reset()], o
2c090 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c r after any call
2c0a0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
2c0b0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 step()] regardle
2c0c0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
2c0d0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 not the stateme
2c0e0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 nt has.** comple
2c0f0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a ted execution..*
2c100 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 *.** ^Invoking s
2c110 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2c120 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) on a NULL poin
2c130 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 ter is a harmles
2c140 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 s no-op..**.** T
2c150 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
2c160 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 ust finalize eve
2c170 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ry [prepared sta
2c180 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 tement] in order
2c190 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 to avoid.** res
2c1a0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 ource leaks. It
2c1b0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 is a grievous e
2c1c0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 rror for the app
2c1d0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 lication to try
2c1e0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 to use.** a prep
2c1f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
2c200 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
2c210 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 finalized. Any
2c220 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 use of a prepar
2c230 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
2c240 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
2c250 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 n finalized can
2c260 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
2c270 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 ned and.** undes
2c280 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 irable behavior
2c290 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 such as segfault
2c2a0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 s and heap corru
2c2b0 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ption..*/.SQLITE
2c2c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2c2d0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 _finalize(sqlite
2c2e0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2c2f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c300 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 Reset A Prepare
2c310 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
2c320 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ct.**.** The sql
2c330 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e ite3_reset() fun
2c340 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
2c350 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 to reset a [prep
2c360 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
2c370 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 ** object back t
2c380 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
2c390 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 ate, ready to be
2c3a0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a re-executed..**
2c3b0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d ^Any SQL statem
2c3c0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 ent variables th
2c3d0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f at had values bo
2c3e0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e und to them usin
2c3f0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 g.** the [sqlite
2c400 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 3_bind_blob | sq
2c410 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 lite3_bind_*() A
2c420 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 PI] retain their
2c430 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 values..** Use
2c440 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 [sqlite3_clear_b
2c450 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 indings()] to re
2c460 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 set the bindings
2c470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ..**.** ^The [sq
2c480 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
2c490 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 interface resets
2c4a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2c4b0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 tatement] S.** b
2c4c0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e ack to the begin
2c4d0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 ning of its prog
2c4e0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ram..**.** ^If t
2c4f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
2c500 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2c510 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
2c520 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
2c530 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 atement] S retur
2c540 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d ned [SQLITE_ROW]
2c550 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 or [SQLITE_DONE
2c560 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c ],.** or if [sql
2c570 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 ite3_step(S)] ha
2c580 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 s never before b
2c590 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c een called on S,
2c5a0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 .** then [sqlite
2c5b0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 3_reset(S)] retu
2c5c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e rns [SQLITE_OK].
2c5d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d .**.** ^If the m
2c5e0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
2c5f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
2c600 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
2c610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2c620 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 ent] S indicated
2c630 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a an error, then.
2c640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2c650 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e t(S)] returns an
2c660 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
2c670 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a ror code]..**.**
2c680 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 ^The [sqlite3_r
2c690 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
2c6a0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e ce does not chan
2c6b0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a ge the values.**
2c6c0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 of any [sqlite3
2c6d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 _bind_blob|bindi
2c6e0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 ngs] on the [pre
2c6f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2c700 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 S..*/.SQLITE_AP
2c710 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 I int sqlite3_re
2c720 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
2c730 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2c740 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
2c750 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
2c760 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
2c770 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
2c780 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
2c790 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
2c7a0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2c7b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2c7c0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
2c7d0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2c7e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2c7f0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions}.**.** ^Th
2c800 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 ese functions (c
2c810 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
2c820 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
2c830 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2c840 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
2c850 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
2c860 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2c870 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
2c880 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
2c890 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
2c8a0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
2c8b0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
2c8c0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 nly differences
2c8d0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 between.** these
2c8e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 routines are th
2c8f0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
2c900 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 expected for.**
2c910 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
2c920 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f eter (the name o
2c930 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 f the function b
2c940 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a eing created).**
2c950 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 and the presenc
2c960 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 e or absence of
2c970 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c a destructor cal
2c980 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 lback for.** the
2c990 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
2c9a0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a a pointer..**.**
2c9b0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
2c9c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
2c9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2c9e0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
2c9f0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
2ca00 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
2ca10 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 ^If an applicat
2ca20 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 ion uses more th
2ca30 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a an one database.
2ca40 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
2ca50 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 en application-d
2ca60 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2ca70 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
2ca80 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 ed.** to each da
2ca90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2caa0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a n separately..**
2cab0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
2cac0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2cad0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
2cae0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2caf0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
2cb00 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c defined. ^The l
2cb10 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
2cb20 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
2cb30 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 255 bytes in a U
2cb40 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e TF-8.** represen
2cb50 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 tation, exclusiv
2cb60 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 e of the zero-te
2cb70 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 rminator. ^Note
2cb80 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a that the name.*
2cb90 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 * length limit i
2cba0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 s in UTF-8 bytes
2cbb0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 , not characters
2cbc0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 nor UTF-16 byte
2cbd0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 s. .** ^Any att
2cbe0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
2cbf0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
2cc00 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
2cc10 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
2cc20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 SQLITE_MISUSE] b
2cc30 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a eing returned..*
2cc40 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
2cc50 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
2cc60 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
2cc70 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
2cc80 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
2cc90 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
2cca0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 gate takes. ^If
2ccb0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 this parameter i
2ccc0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 s -1, then the S
2ccd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
2cce0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
2ccf0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
2cd00 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 of arguments bet
2cd10 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c ween 0 and the l
2cd20 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b imit.** set by [
2cd30 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b sqlite3_limit]([
2cd40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
2cd50 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 CTION_ARG]). If
2cd60 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
2cd70 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 rameter is less
2cd80 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 than -1 or great
2cd90 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e er than 127 then
2cda0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2cdb0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
2cdc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
2cdd0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
2cde0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
2cdf0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
2ce00 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
2ce10 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
2ce20 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
2ce30 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
2ce40 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 eters. Every SQ
2ce50 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
2ce60 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 mentation must b
2ce70 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a e able to work.*
2ce80 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 * with UTF-8, UT
2ce90 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 F-16le, or UTF-1
2cea0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6be. But some i
2ceb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
2cec0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 ay be.** more ef
2ced0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 ficient with one
2cee0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 encoding than a
2cef0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 nother. ^An app
2cf00 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 lication may.**
2cf10 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
2cf20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
2cf30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 or sqlite3_crea
2cf40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 te_function16()
2cf50 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 multiple.** time
2cf60 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
2cf70 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 function but wit
2cf80 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 h different valu
2cf90 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a es of eTextRep..
2cfa0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
2cfb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2cfc0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
2cfd0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
2cfe0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
2cff0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
2d000 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
2d010 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
2d020 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
2d030 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 ion..** If there
2d040 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c is only a singl
2d050 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2d060 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 which does not
2d070 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a care what text.*
2d080 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 * encoding is us
2d090 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 ed, then the fou
2d0a0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rth argument sho
2d0b0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 uld be [SQLITE_A
2d0c0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 NY]..**.** ^(The
2d0d0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
2d0e0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
2d0f0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 pointer. The i
2d100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2d110 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
2d120 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 can gain access
2d130 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 to this pointer
2d140 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2d150 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a user_data()].)^.
2d160 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 **.** ^The sixth
2d170 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 , seventh and ei
2d180 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c ghth parameters,
2d190 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e xFunc, xStep an
2d1a0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a d xFinal, are.**
2d1b0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c pointers to C-l
2d1c0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e anguage function
2d1d0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
2d1e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2d1f0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
2d200 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c e. ^A scalar SQL
2d210 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
2d220 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
2d230 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e tion of the xFun
2d240 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e c.** callback on
2d250 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ly; NULL pointer
2d260 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 s must be passed
2d270 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e as the xStep an
2d280 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 d xFinal.** para
2d290 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 meters. ^An aggr
2d2a0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
2d2b0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
2d2c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2d2d0 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 xStep.** and xF
2d2e0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f inal and NULL po
2d2f0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 inter must be pa
2d300 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 ssed for xFunc.
2d310 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 ^To delete an ex
2d320 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 isting.** SQL fu
2d330 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
2d340 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 ate, pass NULL p
2d350 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 ointers for all
2d360 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a three function.*
2d370 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a * callbacks..**.
2d380 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 ** ^(If the nint
2d390 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2d3a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2d3b0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e nction_v2() is n
2d3c0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e ot NULL,.** then
2d3d0 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f it is destructo
2d3e0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 r for the applic
2d3f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
2d400 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 er. .** The dest
2d410 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 ructor is invoke
2d420 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 d when the funct
2d430 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 ion is deleted,
2d440 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a either by being.
2d450 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 ** overloaded or
2d460 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
2d470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
2d480 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 oses.)^.** ^The
2d490 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c destructor is al
2d4a0 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 so invoked if th
2d4b0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c e call to.** sql
2d4c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2d4d0 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e tion_v2() fails.
2d4e0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 .** ^When the de
2d4f0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
2d500 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 k of the tenth p
2d510 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f arameter is invo
2d520 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 ked, it.** is pa
2d530 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 ssed a single ar
2d540 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
2d550 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 a copy of the ap
2d560 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a plication data .
2d570 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 ** pointer which
2d580 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 was the fifth p
2d590 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2d5a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2d5b0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 ion_v2()..**.**
2d5c0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 ^It is permitted
2d5d0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c to register mul
2d5e0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2d5f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2d600 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 e.** functions w
2d610 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ith the same nam
2d620 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 e but with eithe
2d630 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 r differing numb
2d640 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 ers of.** argume
2d650 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 nts or differing
2d660 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
2d670 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c encodings. ^SQL
2d680 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
2d690 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
2d6a0 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f on that most clo
2d6b0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 sely matches the
2d6c0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 way in which th
2d6d0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f e.** SQL functio
2d6e0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 n is used. ^A f
2d6f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2d700 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f tation with a no
2d710 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 n-negative.** nA
2d720 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rg parameter is
2d730 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 a better match t
2d740 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 han a function i
2d750 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
2d760 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 th.** a negative
2d770 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 nArg. ^A funct
2d780 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 ion where the pr
2d790 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
2d7a0 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 oding.** matches
2d7b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
2d7c0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 coding is a bett
2d7d0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e er.** match than
2d7e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
2d7f0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 e the encoding i
2d800 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a s different. .*
2d810 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 * ^A function wh
2d820 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
2d830 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 difference is b
2d840 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 etween UTF16le a
2d850 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 nd UTF16be.** is
2d860 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 a closer match
2d870 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
2d880 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
2d890 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
2d8a0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 .** between UTF8
2d8b0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a and UTF16..**.*
2d8c0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 * ^Built-in func
2d8d0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 tions may be ove
2d8e0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 rloaded by new a
2d8f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2d900 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ed functions..**
2d910 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 .** ^An applicat
2d920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2d930 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
2d940 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a d to call other.
2d950 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
2d960 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 aces. However,
2d970 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 such calls must
2d980 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 not.** close the
2d990 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2d9a0 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a tion nor finaliz
2d9b0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 e or reset the p
2d9c0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
2d9d0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 ment in which th
2d9e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 e function is ru
2d9f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nning..*/.SQLITE
2da00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2da10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2da20 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2da30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2da40 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
2da50 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
2da60 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
2da70 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
2da80 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
2da90 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
2daa0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
2dab0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
2dac0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2dad0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
2dae0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
2daf0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
2db00 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 ontext*).);.SQLI
2db10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2db20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2db30 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 on16(. sqlite3
2db40 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 *db,. const voi
2db50 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 d *zFunctionName
2db60 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
2db70 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
2db80 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
2db90 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
2dba0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
2dbb0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
2dbc0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
2dbd0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
2dbe0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
2dbf0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
2dc00 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
2dc10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
2dc20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2dc30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2dc40 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c nction_v2(. sql
2dc50 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
2dc60 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
2dc70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
2dc80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
2dc90 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
2dca0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
2dcb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2dcc0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
2dcd0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
2dce0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
2dcf0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
2dd00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
2dd10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
2dd20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2dd30 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
2dd40 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a roy)(void*).);..
2dd50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2dd60 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a Text Encodings.*
2dd70 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
2dd80 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ant define integ
2dd90 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 er codes that re
2dda0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 present the vari
2ddb0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f ous.** text enco
2ddc0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 dings supported
2ddd0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 by SQLite..*/.#d
2dde0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
2ddf0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 8 1.#d
2de00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
2de10 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 16LE 2.#d
2de20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
2de30 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 16BE 3.#d
2de40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
2de50 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 16 4
2de60 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 /* Use native b
2de70 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 yte order */.#de
2de80 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 fine SQLITE_ANY
2de90 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 5
2dea0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 /* sqlite3_creat
2deb0 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 e_function only
2dec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2ded0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 E_UTF16_ALIGNED
2dee0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 8 /* sqlite3
2def0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
2df00 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a n only */../*.**
2df10 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 CAPI3REF: Depre
2df20 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a cated Functions.
2df30 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a ** DEPRECATED.**
2df40 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
2df50 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 ons are [depreca
2df60 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 ted]. In order
2df70 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 to maintain.** b
2df80 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
2df90 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 bility with olde
2dfa0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 r code, these fu
2dfb0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 nctions continue
2dfc0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f .** to be suppo
2dfd0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 rted. However,
2dfe0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
2dff0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a should avoid.**
2e000 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 the use of thes
2e010 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f e functions. To
2e020 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 help encourage
2e030 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a people to avoid.
2e040 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 ** using these f
2e050 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 unctions, we are
2e060 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 not going to te
2e070 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 ll you what they
2e080 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 do..*/.#ifndef
2e090 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 SQLITE_OMIT_DEPR
2e0a0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 ECATED.SQLITE_AP
2e0b0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
2e0c0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
2e0d0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 aggregate_count(
2e0e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2e0f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
2e100 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
2e110 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 int sqlite3_expi
2e120 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 red(sqlite3_stmt
2e130 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
2e140 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
2e150 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 int sqlite3_tra
2e160 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 nsfer_bindings(s
2e170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 qlite3_stmt*, sq
2e180 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 lite3_stmt*);.SQ
2e190 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
2e1a0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
2e1b0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 qlite3_global_re
2e1c0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c cover(void);.SQL
2e1d0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
2e1e0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 EPRECATED void s
2e1f0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c qlite3_thread_cl
2e200 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c eanup(void);.SQL
2e210 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
2e220 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
2e230 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 lite3_memory_ala
2e240 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a rm(void(*)(void*
2e250 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 ,sqlite3_int64,i
2e260 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 nt),void*,sqlite
2e270 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 3_int64);.#endif
2e280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e290 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 : Obtaining SQL
2e2a0 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 Function Paramet
2e2b0 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 er Values.**.**
2e2c0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 The C-language i
2e2d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2e2e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
2e2f0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 nd aggregates us
2e300 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f es.** this set o
2e310 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 f interface rout
2e320 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 ines to access t
2e330 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c he parameter val
2e340 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 ues on.** the fu
2e350 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
2e360 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ate..**.** The x
2e370 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 Func (for scalar
2e380 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 functions) or x
2e390 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 Step (for aggreg
2e3a0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 ates) parameters
2e3b0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
2e3c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2e3d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2e3e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
2e3f0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 6()].** define c
2e400 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d allbacks that im
2e410 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
2e420 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
2e430 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 gregates..** The
2e440 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
2e450 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b o these callback
2e460 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 s is an array of
2e470 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 pointers to.**
2e480 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2e490 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2e4a0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 s. There is one
2e4b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
2e4c0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 object for.** e
2e4d0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f ach parameter to
2e4e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2e4f0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e n. These routin
2e500 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a es are used to.*
2e510 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 * extract values
2e520 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
2e530 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2e540 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
2e550 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c outines work onl
2e560 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 y with [protecte
2e570 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2e580 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 objects..** Any
2e590 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 attempt to use
2e5a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f these routines o
2e5b0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 n an [unprotecte
2e5c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2e5d0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c .** object resul
2e5e0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 ts in undefined
2e5f0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
2e600 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
2e610 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 work just like t
2e620 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
2e630 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
2e640 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 functions].** ex
2e650 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 cept that these
2e660 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 routines take a
2e670 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 single [protect
2e680 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2e690 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e ] object.** poin
2e6a0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 ter instead of a
2e6b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
2e6c0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 pointer and an
2e6d0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e integer column n
2e6e0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 umber..**.** ^Th
2e6f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
2e700 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 text16() interfa
2e710 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 ce extracts a UT
2e720 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 F-16 string.** i
2e730 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
2e740 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 e-order of the h
2e750 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 ost machine. ^T
2e760 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 he.** sqlite3_va
2e770 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 lue_text16be() a
2e780 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nd sqlite3_value
2e790 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 _text16le() inte
2e7a0 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 rfaces.** extrac
2e7b0 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 t UTF-16 strings
2e7c0 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 as big-endian a
2e7d0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e nd little-endian
2e7e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
2e7f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 *.** ^(The sqlit
2e800 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
2e810 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 _type() interfac
2e820 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 e attempts to ap
2e830 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 ply.** numeric a
2e840 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 ffinity to the v
2e850 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e alue. This mean
2e860 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 s that an attemp
2e870 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 t is.** made to
2e880 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 convert the valu
2e890 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 e to an integer
2e8a0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e or floating poin
2e8b0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 t. If.** such a
2e8c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 conversion is p
2e8d0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 ossible without
2e8e0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 loss of informat
2e8f0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a ion (in other.**
2e900 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 words, if the v
2e910 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 alue is a string
2e920 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 that looks like
2e930 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 a number).** th
2e940 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f en the conversio
2e950 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 n is performed.
2e960 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f Otherwise no co
2e970 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e nversion occurs.
2e980 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
2e990 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
2e9a0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 pe] after conver
2e9b0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 sion is returned
2e9c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 .)^.**.** Please
2e9d0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 pay particular
2e9e0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 attention to the
2e9f0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 fact that the p
2ea00 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a ointer returned.
2ea10 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
2ea20 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 _value_blob()],
2ea30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
2ea40 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 ext()], or.** [s
2ea50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2ea60 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e t16()] can be in
2ea70 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 validated by a s
2ea80 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 ubsequent call t
2ea90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 o.** [sqlite3_va
2eaa0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 lue_bytes()], [s
2eab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
2eac0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 es16()], [sqlite
2ead0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
2eae0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
2eaf0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e value_text16()].
2eb00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2eb10 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
2eb20 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
2eb30 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 me thread as.**
2eb40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2eb50 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 that supplied t
2eb60 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
2eb70 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a e*] parameters..
2eb80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2eb90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2eba0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 3_value_blob(sql
2ebb0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
2ebc0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2ebd0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
2ebe0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2ebf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2ec00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
2ec10 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 ytes16(sqlite3_v
2ec20 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
2ec30 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 PI double sqlite
2ec40 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 3_value_double(s
2ec50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2ec60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2ec70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
2ec80 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2ec90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
2eca0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
2ecb0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 e3_value_int64(s
2ecc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2ecd0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2ece0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
2ecf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2ed00 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 xt(sqlite3_value
2ed10 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
2ed20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2ed30 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
2ed40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
2ed50 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2ed60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
2ed70 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 value_text16le(s
2ed80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2ed90 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2eda0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
2edb0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
2edc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
2edd0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2ede0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
2edf0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2ee00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2ee10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
2ee20 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 umeric_type(sqli
2ee30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a te3_value*);../*
2ee40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
2ee50 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 tain Aggregate F
2ee60 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a unction Context.
2ee70 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 **.** Implementa
2ee80 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 tions of aggrega
2ee90 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 te SQL functions
2eea0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 use this.** rou
2eeb0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 tine to allocate
2eec0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 memory for stor
2eed0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e ing their state.
2eee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
2eef0 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 t time the sqlit
2ef00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
2ef10 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
2ef20 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 e is called .**
2ef30 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
2ef40 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
2ef50 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 ion, SQLite.** a
2ef60 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 llocates N of me
2ef70 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 mory, zeroes out
2ef80 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e that memory, an
2ef90 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
2efa0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 ter.** to the ne
2efb0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 w memory. ^On se
2efc0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 cond and subsequ
2efd0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ent calls to.**
2efe0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
2eff0 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 e_context() for
2f000 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
2f010 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
2f020 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d ance,.** the sam
2f030 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 e buffer is retu
2f040 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 rned. Sqlite3_a
2f050 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2f060 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a () is normally.*
2f070 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f * called once fo
2f080 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f r each invocatio
2f090 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 n of the xStep c
2f0a0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e allback and then
2f0b0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d one.** last tim
2f0c0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 e when the xFina
2f0d0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e l callback is in
2f0e0 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e voked. ^(When n
2f0f0 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 o rows match.**
2f100 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 an aggregate que
2f110 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 ry, the xStep()
2f120 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 callback of the
2f130 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
2f140 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 on.** implementa
2f150 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 tion is never ca
2f160 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 lled and xFinal(
2f170 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 ) is called exac
2f180 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 tly once..** In
2f190 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c those cases, sql
2f1a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
2f1b0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 ontext() might b
2f1c0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 e called for the
2f1d0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 .** first time f
2f1e0 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 rom within xFina
2f1f0 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 l().)^.**.** ^Th
2f200 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
2f210 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
2f220 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2f230 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
2f240 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 if N is.** less
2f250 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
2f260 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 zero or if a me
2f270 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 mory allocate er
2f280 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a ror occurs..**.*
2f290 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f * ^(The amount o
2f2a0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 f space allocate
2f2b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 d by sqlite3_agg
2f2c0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
2f2d0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d ,N) is.** determ
2f2e0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 ined by the N pa
2f2f0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 rameter on first
2f300 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
2f310 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a . Changing the.
2f320 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e ** value of N in
2f330 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
2f340 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 to sqlite3_aggr
2f350 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
2f360 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 within.** the sa
2f370 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
2f380 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 ction instance w
2f390 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 ill not resize t
2f3a0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c he memory.** all
2f3b0 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a ocation.)^.**.**
2f3c0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 ^SQLite automat
2f3d0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 ically frees the
2f3e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 memory allocate
2f3f0 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 d by .** sqlite3
2f400 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
2f410 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 xt() when the ag
2f420 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f gregate query co
2f430 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 ncludes..**.** T
2f440 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2f450 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 er must be a cop
2f460 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c y of the.** [sql
2f470 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 ite3_context | S
2f480 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 QL function cont
2f490 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 ext] that is the
2f4a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
2f4b0 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 .** to the xStep
2f4c0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 or xFinal callb
2f4d0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 ack routine that
2f4e0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
2f4f0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e aggregate.** fun
2f500 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ction..**.** Thi
2f510 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
2f520 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
2f530 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
2f540 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 which.** the ag
2f550 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
2f560 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
2f570 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
2f580 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 oid *sqlite3_agg
2f590 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 regate_context(s
2f5a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2f5b0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f int nBytes);../
2f5c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 *.** CAPI3REF: U
2f5d0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e ser Data For Fun
2f5e0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 ctions.**.** ^Th
2f5f0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 e sqlite3_user_d
2f600 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
2f610 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
2f620 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
2f630 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 that was the pU
2f640 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 serData paramete
2f650 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d r (the 5th param
2f660 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
2f670 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2f680 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
2f690 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
2f6a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
2f6b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
2f6c0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
2f6d0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
2f6e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
2f6f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
2f700 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
2f710 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
2f720 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
2f730 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
2f740 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
2f750 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
2f760 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c running..*/.SQL
2f770 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
2f780 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
2f790 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2f7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2f7b0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
2f7c0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 nection For Func
2f7d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tions.**.** ^The
2f7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2f7f0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 _db_handle() int
2f800 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2f810 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
2f820 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
2f830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2f840 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 ion] (the 1st pa
2f850 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
2f860 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2f870 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
2f880 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
2f890 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
2f8a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
2f8b0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
2f8c0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
2f8d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
2f8e0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a ed function..*/.
2f8f0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
2f900 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 e3 *sqlite3_cont
2f910 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
2f920 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
2f930 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2f940 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
2f950 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 iary Data.**.**
2f960 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 The following tw
2f970 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 o functions may
2f980 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 be used by scala
2f990 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 r SQL functions
2f9a0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 to.** associate
2f9b0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 metadata with ar
2f9c0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 gument values. I
2f9d0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 f the same value
2f9e0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a is passed to.**
2f9f0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 multiple invoca
2fa00 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2fa10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 e SQL function d
2fa20 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 uring query exec
2fa30 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 ution, under.**
2fa40 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 some circumstanc
2fa50 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 es the associate
2fa60 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 d metadata may b
2fa70 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 e preserved. Thi
2fa80 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 s may.** be used
2fa90 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 , for example, t
2faa0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d o add a regular-
2fab0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 expression match
2fac0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 ing scalar.** fu
2fad0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 nction. The comp
2fae0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 iled version of
2faf0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
2fb00 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 ession is stored
2fb10 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 as.** metadata
2fb20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2fb30 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 the SQL value pa
2fb40 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 ssed as the regu
2fb50 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a lar expression.*
2fb60 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 * pattern. The
2fb70 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 compiled regular
2fb80 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 expression can
2fb90 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c be reused on mul
2fba0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 tiple.** invocat
2fbb0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
2fbc0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 function so tha
2fbd0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 t the original p
2fbe0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a attern string.**
2fbf0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
2fc00 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 o be recompiled
2fc10 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 on each invocati
2fc20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 on..**.** ^The s
2fc30 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
2fc40 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ta() interface r
2fc50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
2fc60 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 to the metadata
2fc70 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 .** associated b
2fc80 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 y the sqlite3_se
2fc90 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 t_auxdata() func
2fca0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 tion with the Nt
2fcb0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 h argument.** va
2fcc0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 lue to the appli
2fcd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2fce0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 unction. ^If no
2fcf0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 metadata has bee
2fd00 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 n ever.** been s
2fd10 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 et for the Nth a
2fd20 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 rgument of the f
2fd30 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 unction, or if t
2fd40 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
2fd50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
2fd60 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 ameter has chang
2fd70 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 ed since the met
2fd80 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a a-data was set,.
2fd90 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
2fda0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 get_auxdata() re
2fdb0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
2fdc0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nter..**.** ^The
2fdd0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
2fde0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
2fdf0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 saves the metad
2fe00 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 ata.** pointed t
2fe10 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 o by its 3rd par
2fe20 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 ameter as the me
2fe30 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e tadata for the N
2fe40 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 -th.** argument
2fe50 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
2fe60 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2fe70 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 ion. Subsequent
2fe80 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c .** calls to sql
2fe90 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
2fea0 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 () might return
2feb0 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 this data, if it
2fec0 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e has.** not been
2fed0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e destroyed..** ^
2fee0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c If it is not NUL
2fef0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 L, SQLite will i
2ff00 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 nvoke the destru
2ff10 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ctor.** function
2ff20 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 given by the 4t
2ff30 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2ff40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
2ff50 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d ta() on.** the m
2ff60 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 etadata when the
2ff70 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 corresponding f
2ff80 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 unction paramete
2ff90 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 r changes.** or
2ffa0 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 when the SQL sta
2ffb0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 tement completes
2ffc0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
2ffd0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 s first..**.** S
2ffe0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f QLite is free to
2fff0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 call the destru
30000 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 ctor and drop me
30010 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a tadata on any.**
30020 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e parameter of an
30030 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e y function at an
30040 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e y time. ^The on
30050 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 ly guarantee is
30060 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 that.** the dest
30070 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 ructor will be c
30080 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 alled before the
30090 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f metadata is dro
300a0 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e pped..**.** ^(In
300b0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 practice, metad
300c0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 ata is preserved
300d0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f between functio
300e0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 n calls for.** e
300f0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 xpressions that
30100 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 are constant at
30110 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 compile time. Th
30120 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 is includes lite
30130 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e ral.** values an
30140 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 d [parameters].)
30150 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ^.**.** These ro
30160 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
30170 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
30180 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
30190 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 ich.** the SQL f
301a0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
301b0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ng..*/.SQLITE_AP
301c0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
301d0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 get_auxdata(sqli
301e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
301f0 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t N);.SQLITE_API
30200 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 void sqlite3_se
30210 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
30220 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
30230 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 N, void*, void (
30240 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a *)(void*));.../*
30250 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
30260 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 nstants Defining
30270 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 Special Destruc
30280 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a tor Behavior.**.
30290 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 ** These are spe
302a0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 cial values for
302b0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 the destructor t
302c0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e hat is passed in
302d0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c as the.** final
302e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 argument to rou
302f0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 tines like [sqli
30300 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
30310 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 )]. ^If the des
30320 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d tructor.** argum
30330 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 ent is SQLITE_ST
30340 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 ATIC, it means t
30350 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
30360 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 pointer is const
30370 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 ant.** and will
30380 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 never change. I
30390 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 t does not need
303a0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e to be destroyed.
303b0 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 ^The.** SQLITE
303c0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 _TRANSIENT value
303d0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
303e0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b content will lik
303f0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a ely change in.**
30400 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 the near future
30410 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 and that SQLite
30420 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 should make its
30430 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
30440 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 y of.** the cont
30450 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 ent before retur
30460 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ning..**.** The
30470 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 typedef is neces
30480 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f sary to work aro
30490 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 und problems in
304a0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 certain.** C++ c
304b0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 ompilers. See t
304c0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a icket #2191..*/.
304d0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 typedef void (*s
304e0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
304f0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a r_type)(void*);.
30500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
30510 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c TATIC ((sql
30520 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
30530 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 type)0).#define
30540 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
30550 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
30560 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 tructor_type)-1)
30570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
30580 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 : Setting The Re
30590 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 sult Of An SQL F
305a0 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 unction.**.** Th
305b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
305c0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 used by the xFu
305d0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c nc or xFinal cal
305e0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 lbacks that.** i
305f0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e mplement SQL fun
30600 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
30610 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b gates. See.** [
30620 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
30630 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b unction()] and [
30640 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
30650 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 unction16()].**
30660 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
30670 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
30680 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
30690 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 s work very much
306a0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d like the [param
306b0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 eter binding] fa
306c0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 mily of.** funct
306d0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e ions used to bin
306e0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 d values to host
306f0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 parameters in p
30700 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
30710 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 ts..** Refer to
30720 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 the [SQL paramet
30730 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f er] documentatio
30740 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
30750 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
30760 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30770 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 _result_blob() i
30780 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
30790 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a e result from.**
307a0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
307b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
307c0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 to be the BLOB
307d0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 whose content is
307e0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 pointed.** to b
307f0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 y the second par
30800 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 ameter and which
30810 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 is N bytes long
30820 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a where N is the.
30830 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 ** third paramet
30840 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
30850 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
30860 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 roblob() interfa
30870 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 ces set the resu
30880 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
30890 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
308a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
308b0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e a BLOB containin
308c0 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 g all zero.** by
308d0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 tes and N bytes
308e0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e in size, where N
308f0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
30900 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
30910 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
30920 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
30930 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
30940 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
30950 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
30960 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
30970 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
30980 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
30990 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
309a0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
309b0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
309c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
309d0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
309e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
309f0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 or16() functions
30a00 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d .** cause the im
30a10 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 plemented SQL fu
30a20 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 nction to throw
30a30 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a an exception..**
30a40 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
30a50 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 e string pointed
30a60 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e to by the.** 2n
30a70 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 d parameter of s
30a80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
30a90 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ror() or sqlite3
30aa0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
30ab0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 ).** as the text
30ac0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 of an error mes
30ad0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 sage. ^SQLite i
30ae0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 nterprets the er
30af0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 ror.** message s
30b00 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 tring from sqlit
30b10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
30b20 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c ) as UTF-8. ^SQL
30b30 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ite.** interpret
30b40 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f s the string fro
30b50 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
30b60 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 _error16() as UT
30b70 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a F-16 in native.*
30b80 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e * byte order. ^
30b90 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
30ba0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
30bb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
30bc0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
30bd0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
30be0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e is negative then
30bf0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 SQLite takes as
30c00 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 the error.** me
30c10 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 ssage all text u
30c20 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 p through the fi
30c30 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
30c40 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
30c50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
30c60 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
30c70 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 _error() or.** s
30c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
30c90 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e ror16() is non-n
30ca0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c egative then SQL
30cb0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d ite takes that m
30cc0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f any.** bytes (no
30cd0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 t characters) fr
30ce0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
30cf0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f eter as the erro
30d00 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 r message..** ^T
30d10 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
30d20 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
30d30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
30d40 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e or16().** routin
30d50 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 es make a privat
30d60 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 e copy of the er
30d70 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 ror message text
30d80 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 before.** they
30d90 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 return. Hence,
30da0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
30db0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 tion can dealloc
30dc0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 ate or.** modify
30dd0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 the text after
30de0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 they return with
30df0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 out harm..** ^Th
30e00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
30e10 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 _error_code() fu
30e20 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 nction changes t
30e30 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a he error code.**
30e40 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c returned by SQL
30e50 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 ite as a result
30e60 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 of an error in a
30e70 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 function. ^By
30e80 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 default,.** the
30e90 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 error code is SQ
30ea0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 LITE_ERROR. ^A
30eb0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
30ec0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
30ed0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
30ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
30ef0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 rror16() resets
30f00 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 the error code t
30f10 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a o SQLITE_ERROR..
30f20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
30f30 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 e3_result_toobig
30f40 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 () interface cau
30f50 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 ses SQLite to th
30f60 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 row an error.**
30f70 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 indicating that
30f80 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 a string or BLOB
30f90 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 is too long to
30fa0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a represent..**.**
30fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
30fc0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 sult_nomem() int
30fd0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 erface causes SQ
30fe0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e Lite to throw an
30ff0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 error.** indica
31000 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f ting that a memo
31010 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
31020 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 iled..**.** ^The
31030 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31040 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 int() interface
31050 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
31060 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
31070 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
31080 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
31090 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 be the 32-bit si
310a0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
310b0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 value given in t
310c0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e he 2nd argument.
310d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
310e0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 _result_int64()
310f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
31100 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
31110 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
31120 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
31130 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
31140 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
31150 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 nteger.** value
31160 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 given in the 2nd
31170 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
31180 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
31190 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 sult_null() inte
311a0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
311b0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
311c0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
311d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
311e0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a on to be NULL..*
311f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
31200 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 3_result_text(),
31210 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31220 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c text16(),.** sql
31230 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
31240 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 16le(), and sqli
31250 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
31260 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6be() interfaces
31270 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 .** set the retu
31280 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
31290 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
312a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
312b0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 be.** a text str
312c0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 ing which is rep
312d0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d resented as UTF-
312e0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 8, UTF-16 native
312f0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 byte order,.**
31300 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e UTF-16 little en
31310 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 dian, or UTF-16
31320 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 big endian, resp
31330 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 ectively..** ^SQ
31340 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 Lite takes the t
31350 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 ext result from
31360 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
31370 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 from.** the 2nd
31380 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
31390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
313a0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
313b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 ..** ^If the 3rd
313c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
313d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
313e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
313f0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 s.** is negative
31400 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 , then SQLite ta
31410 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 kes result text
31420 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
31430 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 ameter.** throug
31440 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
31450 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e character..** ^
31460 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
31470 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
31480 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
31490 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
314a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
314b0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 then as many byt
314c0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
314d0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a rs) of the text.
314e0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
314f0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
31500 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 er are taken as
31510 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
31520 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 defined.** funct
31530 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 ion result. If
31540 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
31550 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 r is non-negativ
31560 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 e, then it.** mu
31570 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
31580 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 ffset into the s
31590 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 tring where the
315a0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
315b0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 ould.** appear i
315c0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 f the string whe
315d0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 re NUL terminate
315e0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 d. If any NUL c
315f0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a haracters occur.
31600 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 ** in the string
31610 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 at a byte offse
31620 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 t that is less t
31630 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 han the value of
31640 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 the 3rd.** para
31650 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
31660 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
31670 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d will contain em
31680 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 bedded NULs and
31690 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 the.** result of
316a0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 expressions ope
316b0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 rating on string
316c0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 s with embedded
316d0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 NULs is undefine
316e0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 d..** ^If the 4t
316f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
31700 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
31710 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
31720 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
31730 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
31740 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
31750 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
31760 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 calls that.** fu
31770 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 nction as the de
31780 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 structor on the
31790 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
317a0 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a ult when it has.
317b0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e ** finished usin
317c0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
317d0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
317e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
317f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
31800 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f xt* interfaces o
31810 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
31820 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
31830 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
31840 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
31850 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
31860 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
31870 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
31880 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
31890 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
318a0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
318b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
318c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f the parameter no
318d0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 r call a destruc
318e0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 tor on the conte
318f0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 nt.** when it ha
31900 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
31910 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
31920 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
31930 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
31940 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
31950 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
31960 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
31970 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
31980 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
31990 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
319a0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 .** then SQLite
319b0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
319c0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 the result into
319d0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 space obtained f
319e0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c rom.** from [sql
319f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
31a00 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
31a10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
31a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
31a30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
31a40 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 ts the result of
31a50 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
31a60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
31a70 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 tion to be a cop
31a80 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 y the.** [unprot
31a90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
31aa0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 lue] object spec
31ab0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 ified by the 2nd
31ac0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 parameter. ^Th
31ad0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 e.** sqlite3_res
31ae0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 ult_value() inte
31af0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f rface makes a co
31b00 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 py of the [sqlit
31b10 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 e3_value].** so
31b20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 that the [sqlite
31b30 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 3_value] specifi
31b40 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 ed in the parame
31b50 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f ter may change o
31b60 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 r.** be dealloca
31b70 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 ted after sqlite
31b80 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
31b90 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 returns without
31ba0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 harm..** ^A [pr
31bb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
31bc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 value] object ma
31bd0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 y always be used
31be0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e where an.** [un
31bf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
31c00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
31c10 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 is required, so
31c20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f either.** kind o
31c30 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 f [sqlite3_value
31c40 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 ] object can be
31c50 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 used with this i
31c60 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
31c70 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 If these routine
31c80 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f s are called fro
31c90 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 m within the dif
31ca0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a ferent thread.**
31cb0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f than the one co
31cc0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 ntaining the app
31cd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
31ce0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 function that r
31cf0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b eceived.** the [
31d00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d sqlite3_context]
31d10 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 pointer, the re
31d20 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
31d30 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ned..*/.SQLITE_A
31d40 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
31d50 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 result_blob(sqli
31d60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
31d70 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
31d80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
31d90 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
31da0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31db0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 double(sqlite3_c
31dc0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 ontext*, double)
31dd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
31de0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
31df0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 _error(sqlite3_c
31e00 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 ontext*, const c
31e10 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 har*, int);.SQLI
31e20 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
31e30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
31e40 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
31e50 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
31e60 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
31e70 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
31e80 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f result_error_too
31e90 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 big(sqlite3_cont
31ea0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
31eb0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
31ec0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
31ed0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 m(sqlite3_contex
31ee0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
31ef0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
31f00 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 ult_error_code(s
31f10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
31f20 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
31f30 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
31f40 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 esult_int(sqlite
31f50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
31f60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
31f70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
31f80 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 _int64(sqlite3_c
31f90 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 ontext*, sqlite3
31fa0 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f _int64);.SQLITE_
31fb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
31fc0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c _result_null(sql
31fd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
31fe0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
31ff0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
32000 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext(sqlite3_cont
32010 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 ext*, const char
32020 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
32030 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
32040 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
32050 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 _result_text16(s
32060 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
32070 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
32080 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
32090 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 ));.SQLITE_API v
320a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
320b0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 lt_text16le(sqli
320c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
320d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
320e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
320f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
32100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
32110 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
32120 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
32130 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
32140 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
32150 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
32160 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
32170 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32180 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 *, sqlite3_value
32190 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
321a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
321b0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 lt_zeroblob(sqli
321c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
321d0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t n);../*.** CAP
321e0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 I3REF: Define Ne
321f0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 w Collating Sequ
32200 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ences.**.** ^The
32210 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 se functions add
32220 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 , remove, or mod
32230 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e ify a [collation
32240 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 ] associated.**
32250 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
32260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
32270 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 pecified as the
32280 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
32290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 **.** ^The name
322a0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e of the collation
322b0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
322c0 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 ng.** for sqlite
322d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
322e0 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 on() and sqlite3
322f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
32300 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 n_v2().** and a
32310 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e UTF-16 string in
32320 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
32330 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 er for sqlite3_c
32340 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
32350 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6()..** ^Collati
32360 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f on names that co
32370 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f mpare equal acco
32380 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 rding to [sqlite
32390 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 3_strnicmp()] ar
323a0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 e.** considered
323b0 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e to be the same n
323c0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ame..**.** ^(The
323d0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
323e0 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 (eTextRep) must
323f0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f be one of the co
32400 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e nstants:.** <ul>
32410 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
32420 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _UTF8],.** <li>
32430 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
32440 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
32450 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c E_UTF16BE],.** <
32460 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 li> [SQLITE_UTF1
32470 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 6], or.** <li> [
32480 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
32490 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 GNED]..** </ul>)
324a0 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 ^.** ^The eTextR
324b0 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 ep argument dete
324c0 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 rmines the encod
324d0 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 ing of strings p
324e0 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 assed.** to the
324f0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
32500 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 on callback, xCa
32510 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 llback..** ^The
32520 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 [SQLITE_UTF16] a
32530 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 nd [SQLITE_UTF16
32540 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 _ALIGNED] values
32550 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a for eTextRep.**
32560 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 force strings t
32570 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 o be UTF16 with
32580 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
32590 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 r..** ^The [SQLI
325a0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
325b0 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 ] value for eTex
325c0 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 tRep forces stri
325d0 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 ngs to begin.**
325e0 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 on an even byte
325f0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e address..**.** ^
32600 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d The fourth argum
32610 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e ent, pArg, is an
32620 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
32630 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 a pointer that i
32640 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f s passed.** thro
32650 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 ugh as the first
32660 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
32670 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
32680 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ion callback..**
32690 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 .** ^The fifth a
326a0 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 rgument, xCallba
326b0 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ck, is a pointer
326c0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e to the collatin
326d0 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e g function..** ^
326e0 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 Multiple collati
326f0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e ng functions can
32700 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 be registered u
32710 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 sing the same na
32720 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 me but.** with d
32730 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 ifferent eTextRe
32740 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 p parameters and
32750 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
32760 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 whichever.** fu
32770 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
32780 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
32790 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f of data transfo
327a0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 rmation..** ^If
327b0 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 the xCallback ar
327c0 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 gument is NULL t
327d0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e hen the collatin
327e0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a g function is.**
327f0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e deleted. ^When
32800 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 all collating f
32810 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 unctions having
32820 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 the same name ar
32830 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 e deleted,.** th
32840 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 at collation is
32850 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 no longer usable
32860 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c ..**.** ^The col
32870 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
32880 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
32890 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 ked with a copy
328a0 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 of the pArg .**
328b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
328c0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 pointer and wit
328d0 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e h two strings in
328e0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 the encoding sp
328f0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 ecified.** by th
32900 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d e eTextRep argum
32910 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 ent. The collat
32920 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 ing function mus
32930 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 t return an.** i
32940 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e nteger that is n
32950 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f egative, zero, o
32960 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 r positive.** if
32970 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e the first strin
32980 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 g is less than,
32990 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 equal to, or gre
329a0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 ater than the se
329b0 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 cond,.** respect
329c0 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 ively. A collat
329d0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 ing function mus
329e0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 t always return
329f0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a the same answer.
32a00 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d ** given the sam
32a10 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 e inputs. If tw
32a20 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 o or more collat
32a30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ing functions ar
32a40 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 e registered.**
32a50 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c to the same coll
32a60 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e ation name (usin
32a70 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 g different eTex
32a80 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 tRep values) the
32a90 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 n all.** must gi
32aa0 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 ve an equivalent
32ab0 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 answer when inv
32ac0 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 oked with equiva
32ad0 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a lent strings..**
32ae0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
32af0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 unction must obe
32b00 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 y the following
32b10 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 properties for a
32b20 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c ll.** strings A,
32b30 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a B, and C:.**.**
32b40 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 <ol>.** <li> If
32b50 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e A==B then B==A.
32b60 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
32b70 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 and B==C then A
32b80 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 ==C..** <li> If
32b90 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 A<B THEN B>
32ba0 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 ;A..** <li> If A
32bb0 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 <B and B<C
32bc0 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a then A<C..**
32bd0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </ol>.**.** If
32be0 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 a collating func
32bf0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f tion fails any o
32c00 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 f the above cons
32c10 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 traints and that
32c20 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 .** collating fu
32c30 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 nction is regis
32c40 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 tered and used,
32c50 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
32c60 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 r of SQLite.** i
32c70 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
32c80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
32c90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
32ca0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 _v2() works like
32cb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
32cc0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 collation().** w
32cd0 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e ith the addition
32ce0 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 that the xDestr
32cf0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 oy callback is i
32d00 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 nvoked on pArg w
32d10 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 hen.** the colla
32d20 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
32d30 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f deleted..** ^Co
32d40 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
32d50 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 s are deleted wh
32d60 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 en they are over
32d70 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a ridden by later.
32d80 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 ** calls to the
32d90 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 collation creati
32da0 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 on functions or
32db0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 when the.** [dat
32dc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
32dd0 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e ] is closed usin
32de0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 g [sqlite3_close
32df0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ()]..**.** ^The
32e00 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 xDestroy callbac
32e10 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 k is <u>not</u>
32e20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a called if the .*
32e30 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
32e40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
32e50 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 function fails.
32e60 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
32e70 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c at invoke.** sql
32e80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
32e90 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 ation_v2() with
32ea0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 a non-NULL xDest
32eb0 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f roy argument sho
32ec0 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 uld .** check th
32ed0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e e return code an
32ee0 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 d dispose of the
32ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
32f00 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 a pointer.** the
32f10 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 mselves rather t
32f20 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 han expecting SQ
32f30 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 Lite to deal wit
32f40 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a h it for them..*
32f50 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 * This is differ
32f60 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f ent from every o
32f70 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
32f80 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f rface. The inco
32f90 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 nsistency .** is
32fa0 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 unfortunate but
32fb0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 cannot be chang
32fc0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
32fd0 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a ing backwards .*
32fe0 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e * compatibility.
32ff0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
33000 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 [sqlite3_colla
33010 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 tion_needed()] a
33020 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c nd [sqlite3_coll
33030 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
33040 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
33050 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
33060 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 ate_collation(.
33070 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
33080 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
33090 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
330a0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
330b0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
330c0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
330d0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
330e0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 t void*).);.SQLI
330f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
33100 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
33110 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 ion_v2(. sqlite
33120 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 3*, . const cha
33130 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 r *zName, . int
33140 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
33150 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 id *pArg,. int(
33160 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
33170 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
33180 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
33190 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
331a0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 roy)(void*).);.S
331b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
331c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
331d0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 lation16(. sqli
331e0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 te3*, . const v
331f0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e oid *zName,. in
33200 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
33210 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 oid *pArg,. int
33220 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 (*xCompare)(void
33230 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
33240 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
33250 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
33260 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e I3REF: Collation
33270 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b Needed Callback
33280 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 s.**.** ^To avoi
33290 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 d having to regi
332a0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 ster all collati
332b0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 on sequences bef
332c0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a ore a database.*
332d0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 * can be used, a
332e0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b single callback
332f0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
33300 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
33310 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
33320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f e connection] to
33330 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
33340 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 ever an undefine
33350 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 d collation.** s
33360 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 equence is requi
33370 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 red..**.** ^If t
33380 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
33390 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
333a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c the sqlite3_coll
333b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 ation_needed() A
333c0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 PI,.** then it i
333d0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d s passed the nam
333e0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 es of undefined
333f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
33400 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a ces as strings.*
33410 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 * encoded in UTF
33420 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f -8. ^If sqlite3_
33430 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
33440 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 16() is used,.**
33450 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 the names are p
33460 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 assed as UTF-16
33470 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 in machine nativ
33480 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
33490 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 ^A call to eith
334a0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c er function repl
334b0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e aces the existin
334c0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 g collation-need
334d0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a ed callback..**.
334e0 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 ** ^(When the ca
334f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
33500 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 d, the first arg
33510 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 ument passed is
33520 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 a copy.** of the
33530 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
33540 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c to sqlite3_coll
33550 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f ation_needed() o
33560 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
33570 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
33580 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 ). The second a
33590 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 rgument is the d
335a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
335b0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 ction. The thir
335c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e d argument is on
335d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 e of [SQLITE_UTF
335e0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 8], [SQLITE_UTF1
335f0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 6BE],.** or [SQL
33600 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e ITE_UTF16LE], in
33610 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 dicating the mos
33620 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d t desirable form
33630 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f of the collatio
33640 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 n.** sequence fu
33650 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e nction required.
33660 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 The fourth par
33670 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 ameter is the na
33680 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 me of the.** req
33690 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 uired collation
336a0 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a sequence.)^.**.*
336b0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
336c0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 unction should r
336d0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 egister the desi
336e0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 red collation us
336f0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
33700 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
33710 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
33720 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
33730 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
33740 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
33750 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 tion_v2()]..*/.S
33760 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
33770 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
33780 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 needed(. sqlite
33790 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 3*, . void*, .
337a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
337b0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
337c0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a tRep,const char*
337d0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ).);.SQLITE_API
337e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c int sqlite3_coll
337f0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a ation_needed16(.
33800 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
33810 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 oid*,. void(*)(
33820 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 void*,sqlite3*,i
33830 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 nt eTextRep,cons
33840 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 t void*).);..#if
33850 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 def SQLITE_HAS_C
33860 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 ODEC./*.** Speci
33870 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 fy the key for a
33880 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 n encrypted data
33890 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 base. This rout
338a0 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ine should be.**
338b0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 called right af
338c0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ter sqlite3_open
338d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ()..**.** The co
338e0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 de to implement
338f0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 this API is not
33900 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 available in the
33910 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a public release.
33920 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ** of SQLite..*/
33930 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
33940 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 sqlite3_key(. s
33950 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
33960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
33970 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 Database to be
33980 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e rekeyed */. con
33990 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
339a0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
339b0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a he key */.);../*
339c0 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b .** Change the k
339d0 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 ey on an open da
339e0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 tabase. If the
339f0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 current database
33a00 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 is not.** encry
33a10 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 pted, this routi
33a20 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 ne will encrypt
33a30 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 it. If pNew==0
33a40 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a or nNew==0, the.
33a50 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 ** database is d
33a60 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ecrypted..**.**
33a70 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c The code to impl
33a80 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 ement this API i
33a90 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
33aa0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 in the public re
33ab0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 lease.** of SQLi
33ac0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 te..*/.SQLITE_AP
33ad0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 I int sqlite3_re
33ae0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
33af0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
33b00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
33b10 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
33b20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
33b30 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
33b40 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b /* The new k
33b50 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ey */.);../*.**
33b60 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 Specify the acti
33b70 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 vation key for a
33b80 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 SEE database.
33b90 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 Unless .** activ
33ba0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 ated, none of th
33bb0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 e SEE routines w
33bc0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c ill work..*/.SQL
33bd0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
33be0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 ite3_activate_se
33bf0 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 e(. const char
33c00 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 *zPassPhrase
33c10 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f /* Activatio
33c20 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 n phrase */.);.#
33c30 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 endif..#ifdef SQ
33c40 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f LITE_ENABLE_CERO
33c50 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 D./*.** Specify
33c60 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b the activation k
33c70 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 ey for a CEROD d
33c80 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 atabase. Unless
33c90 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 .** activated,
33ca0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f none of the CERO
33cb0 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 D routines will
33cc0 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f work..*/.SQLITE_
33cd0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
33ce0 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 _activate_cerod(
33cf0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
33d00 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 PassPhrase
33d10 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 /* Activation
33d20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e phrase */.);.#en
33d30 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
33d40 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 REF: Suspend Exe
33d50 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
33d60 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 rt Time.**.** Th
33d70 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 e sqlite3_sleep(
33d80 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 ) function cause
33d90 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 s the current th
33da0 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 read to suspend
33db0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 execution.** for
33dc0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 at least a numb
33dd0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
33de0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 ds specified in
33df0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a its parameter..*
33e00 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 *.** If the oper
33e10 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
33e20 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
33e30 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
33e40 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 h.** millisecond
33e50 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e time resolution
33e60 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 , then the time
33e70 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 will be rounded
33e80 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 up to.** the nea
33e90 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 rest second. The
33ea0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 number of milli
33eb0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
33ec0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 actually.** req
33ed0 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 uested from the
33ee0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
33ef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
33f00 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c .** ^SQLite impl
33f10 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 ements this inte
33f20 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 rface by calling
33f30 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a the xSleep().**
33f40 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 method of the d
33f50 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
33f60 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 vfs] object. If
33f70 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 the xSleep() me
33f80 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 thod.** of the d
33f90 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f efault VFS is no
33fa0 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f t implemented co
33fb0 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 rrectly, or not
33fc0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a implemented at.*
33fd0 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 * all, then the
33fe0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
33ff0 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 te3_sleep() may
34000 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 deviate from the
34010 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 description.**
34020 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
34030 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 paragraphs..*/.S
34040 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
34050 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 lite3_sleep(int)
34060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
34070 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 F: Name Of The F
34080 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 older Holding Te
34090 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a mporary Files.**
340a0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c .** ^(If this gl
340b0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 obal variable is
340c0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
340d0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
340e0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 is.** the name
340f0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b of a folder (a.k
34100 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 .a. directory),
34110 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 then all tempora
34120 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 ry files.** crea
34130 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 ted by SQLite wh
34140 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 en using a built
34150 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 -in [sqlite3_vfs
34160 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 | VFS].** will
34170 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 be placed in tha
34180 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 t directory.)^
34190 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c ^If this variabl
341a0 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 e.** is a NULL p
341b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
341c0 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 ite performs a s
341d0 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 earch for an app
341e0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 ropriate.** temp
341f0 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 orary file direc
34200 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 tory..**.** It i
34210 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 s not safe to re
34220 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ad or modify thi
34230 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f s variable in mo
34240 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 re than one.** t
34250 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e hread at a time.
34260 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 It is not safe
34270 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 to read or modi
34280 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
34290 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 .** if a [databa
342a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
342b0 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 s being used at
342c0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e the same time in
342d0 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 a separate.** t
342e0 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 hread..** It is
342f0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 intended that th
34300 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 is variable be s
34310 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 et once.** as pa
34320 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e rt of process in
34330 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
34340 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 before any SQLi
34350 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 te interface.**
34360 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 routines have be
34370 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 en called and th
34380 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
34390 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 remain unchange
343a0 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e d.** thereafter.
343b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d .**.** ^The [tem
343c0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
343d0 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f y pragma] may mo
343e0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
343f0 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 le and cause.**
34400 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d it to point to m
34410 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
34420 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
34430 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d loc]. ^Furtherm
34440 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d ore,.** the [tem
34450 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
34460 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 y pragma] always
34470 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e assumes that an
34480 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 y string.** that
34490 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 this variable p
344a0 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 oints to is held
344b0 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 in memory obtai
344c0 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 ned from .** [sq
344d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e lite3_malloc] an
344e0 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 d the pragma may
344f0 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 attempt to free
34500 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 that memory.**
34510 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
34520 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 ree]..** Hence,
34530 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 if this variable
34540 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 is modified dir
34550 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 ectly, either it
34560 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 should be.** ma
34570 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 de NULL or made
34580 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f to point to memo
34590 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
345a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
345b0 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 ].** or else the
345c0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d use of the [tem
345d0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
345e0 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 y pragma] should
345f0 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a be avoided..*/.
34600 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
34610 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 E_EXTERN char *s
34620 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
34630 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ctory;../*.** CA
34640 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 PI3REF: Test For
34650 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 Auto-Commit Mod
34660 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b e.** KEYWORDS: {
34670 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d autocommit mode}
34680 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
34690 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d te3_get_autocomm
346a0 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 it() interface r
346b0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 eturns non-zero
346c0 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 or.** zero if th
346d0 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 e given database
346e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
346f0 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f r is not in auto
34700 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 commit mode,.**
34710 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e respectively. ^
34720 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
34730 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 is on by default
34740 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 ..** ^Autocommit
34750 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 mode is disable
34760 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 d by a [BEGIN] s
34770 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 tatement..** ^Au
34780 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
34790 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 re-enabled by a
347a0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f [COMMIT] or [RO
347b0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 LLBACK]..**.** I
347c0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 f certain kinds
347d0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 of errors occur
347e0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 on a statement w
347f0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 ithin a multi-st
34800 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 atement.** trans
34810 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 action (errors i
34820 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 ncluding [SQLITE
34830 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f _FULL], [SQLITE_
34840 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 IOERR],.** [SQLI
34850 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 TE_NOMEM], [SQLI
34860 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 TE_BUSY], and [S
34870 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
34880 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 ) then the.** tr
34890 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 ansaction might
348a0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 be rolled back a
348b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 utomatically. T
348c0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a he only way to.*
348d0 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 * find out wheth
348e0 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 er SQLite automa
348f0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
34900 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
34910 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 ion after.** an
34920 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 error is to use
34930 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a this function..*
34940 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 *.** If another
34950 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 thread changes t
34960 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 he autocommit st
34970 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 atus of the data
34980 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
34990 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f on while this ro
349a0 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 utine is running
349b0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 , then the retur
349c0 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e n value.** is un
349d0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 defined..*/.SQLI
349e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
349f0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 e3_get_autocommi
34a00 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
34a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
34a20 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 nd The Database
34a30 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 Handle Of A Prep
34a40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a ared Statement.*
34a50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
34a60 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 3_db_handle inte
34a70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
34a80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
34a90 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a ection] handle.*
34aa0 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 * to which a [pr
34ab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
34ac0 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 ] belongs. ^The
34ad0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
34ae0 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e ction].** return
34af0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 ed by sqlite3_db
34b00 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 _handle is the s
34b10 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
34b20 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 nnection].** tha
34b30 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 t was the first
34b40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 argument.** to t
34b50 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
34b60 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 are_v2()] call (
34b70 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 or its variants)
34b80 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 that was used t
34b90 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 o.** create the
34ba0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
34bb0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f first place..*/
34bc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
34bd0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f te3 *sqlite3_db_
34be0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 handle(sqlite3_s
34bf0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
34c00 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 PI3REF: Return T
34c10 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 he Filename For
34c20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
34c30 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ction.**.** ^The
34c40 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 sqlite3_db_file
34c50 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 name(D,N) interf
34c60 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
34c70 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e inter to a filen
34c80 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ame.** associate
34c90 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20 d with database
34ca0 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 N of connection
34cb0 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 D. ^The main da
34cc0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 tabase file.** h
34cd0 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 as the name "mai
34ce0 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 n". If there is
34cf0 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 no attached dat
34d00 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 abase N on the d
34d10 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
34d20 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 ction D, or if d
34d30 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 atabase N is a t
34d40 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d emporary or in-m
34d50 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 emory database,
34d60 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 then.** a NULL p
34d70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
34d80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
34d90 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 ilename returned
34da0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f by this functio
34db0 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 n is the output
34dc0 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 of the.** xFullP
34dd0 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f athname method o
34de0 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 f the [VFS]. ^I
34df0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
34e00 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 he filename.** w
34e10 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 ill be an absolu
34e20 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 te pathname, eve
34e30 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d n if the filenam
34e40 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 e used.** to ope
34e50 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f n the database o
34e60 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 riginally was a
34e70 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 URI or relative
34e80 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c pathname..*/.SQL
34e90 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
34ea0 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 ar *sqlite3_db_f
34eb0 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 ilename(sqlite3
34ec0 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 *db, const char
34ed0 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a *zDbName);../*.*
34ee0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 * CAPI3REF: Find
34ef0 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 the next prepar
34f00 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a ed statement.**.
34f10 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 ** ^This interfa
34f20 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
34f30 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 nter to the next
34f40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
34f50 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 ment] after.** p
34f60 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 Stmt associated
34f70 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
34f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
34f90 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 Db. ^If pStmt i
34fa0 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 s NULL.** then t
34fb0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 his interface re
34fc0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
34fd0 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 to the first pre
34fe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
34ff0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
35000 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 th the database
35010 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 connection pDb.
35020 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 ^If no prepared
35030 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 statement.** sa
35040 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 tisfies the cond
35050 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 itions of this r
35060 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 outine, it retur
35070 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 ns NULL..**.** T
35080 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
35090 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 nection] pointer
350a0 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a D in a call to.
350b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 ** [sqlite3_next
350c0 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 _stmt(D,S)] must
350d0 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 refer to an ope
350e0 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f n database.** co
350f0 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 nnection and in
35100 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 particular must
35110 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f not be a NULL po
35120 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 inter..*/.SQLITE
35130 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 73 74 6d _API sqlite3_stm
35140 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f t *sqlite3_next_
35150 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 stmt(sqlite3 *pD
35160 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 b, sqlite3_stmt
35170 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
35180 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 CAPI3REF: Commit
35190 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f And Rollback No
351a0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 tification Callb
351b0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 acks.**.** ^The
351c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
351d0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 ook() interface
351e0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
351f0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
35200 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
35210 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 henever a transa
35220 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 ction is [COMMIT
35230 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a | committed]..*
35240 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 * ^Any callback
35250 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
35260 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
35270 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 3_commit_hook().
35280 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
35290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
352a0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
352b0 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 n..** ^The sqlit
352c0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
352d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 () interface reg
352e0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
352f0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f k.** function to
35300 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
35310 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 ever a transacti
35320 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 on is [ROLLBACK
35330 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a | rolled back]..
35340 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b ** ^Any callback
35350 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
35360 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 us call to sqlit
35370 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
35380 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 ().** for the sa
35390 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
353a0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 ection is overri
353b0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 dden..** ^The pA
353c0 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 rg argument is p
353d0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f assed through to
353e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
353f0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 * ^If the callba
35400 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 ck on a commit h
35410 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 ook function ret
35420 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a urns non-zero,.*
35430 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 * then the commi
35440 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 t is converted i
35450 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a nto a rollback..
35460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
35470 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 e3_commit_hook(D
35480 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 ,C,P) and sqlite
35490 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
354a0 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 D,C,P) functions
354b0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 .** return the P
354c0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 argument from t
354d0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
354e0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
354f0 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 ction.** on the
35500 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
35510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 onnection] D, or
35520 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 NULL for.** the
35530 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 first call for
35540 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e each function on
35550 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f D..**.** The co
35560 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 mmit and rollbac
35570 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 k hook callbacks
35580 20 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 are not reentra
35590 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 nt..** The callb
355a0 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ack implementati
355b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 on must not do a
355c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
355d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
355e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
355f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
35600 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 the callback.
35610 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 Any actions.** t
35620 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 o modify the dat
35630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
35640 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 must be deferre
35650 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 d until after th
35660 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 e.** completion
35670 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
35680 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 step()] call tha
35690 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 t triggered the
356a0 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c commit.** or rol
356b0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 lback hook in th
356c0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
356d0 2a 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e * Note that runn
356e0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
356f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e L statements, in
35700 63 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 cluding SELECT s
35710 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 tatements,.** or
35720 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 merely calling
35730 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
35740 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
35750 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
35760 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
35770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
35780 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
35790 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
357a0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
357b0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 h..**.** ^Regist
357c0 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e ering a NULL fun
357d0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 ction disables t
357e0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a he callback..**.
357f0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d ** ^When the com
35800 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 mit hook callbac
35810 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e k routine return
35820 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d s zero, the [COM
35830 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f MIT].** operatio
35840 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 n is allowed to
35850 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c continue normall
35860 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d y. ^If the comm
35870 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 it hook.** retur
35880 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
35890 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 n the [COMMIT] i
358a0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f s converted into
358b0 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a a [ROLLBACK]..*
358c0 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 * ^The rollback
358d0 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 hook is invoked
358e0 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 on a rollback th
358f0 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 at results from
35900 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b a commit.** hook
35910 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a returning non-z
35920 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 ero, just as it
35930 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e would be with an
35940 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b y other rollback
35950 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 ..**.** ^For the
35960 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
35970 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 s API, a transac
35980 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 tion is said to
35990 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c have been.** rol
359a0 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 led back if an e
359b0 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 xplicit "ROLLBAC
359c0 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 K" statement is
359d0 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 executed, or.**
359e0 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 an error or cons
359f0 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e traint causes an
35a00 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 implicit rollba
35a10 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 ck to occur..**
35a20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 ^The rollback ca
35a30 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e llback is not in
35a40 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 voked if a trans
35a50 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 action is.** aut
35a60 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
35a70 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 d back because t
35a80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
35a90 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
35aa0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
35ab0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 the [sqlite3_up
35ac0 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 date_hook()] int
35ad0 65 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 erface..*/.SQLIT
35ae0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
35af0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
35b00 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 sqlite3*, int(*)
35b10 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b (void*), void*);
35b20 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
35b30 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 *sqlite3_rollba
35b40 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a ck_hook(sqlite3*
35b50 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a , void(*)(void *
35b60 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
35b70 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
35b80 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 Change Notifica
35b90 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a tion Callbacks.*
35ba0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35bb0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 3_update_hook()
35bc0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
35bd0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
35be0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 unction.** with
35bf0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
35c00 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 nnection] identi
35c10 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
35c20 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f t argument.** to
35c30 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
35c40 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 ever a row is up
35c50 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
35c60 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e or deleted..** ^
35c70 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 Any callback set
35c80 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 by a previous c
35c90 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 all to this func
35ca0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 tion.** for the
35cb0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
35cc0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 nnection is over
35cd0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ridden..**.** ^T
35ce0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
35cf0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
35d00 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 to the function
35d10 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 to invoke when a
35d20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 .** row is updat
35d30 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
35d40 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 deleted..** ^The
35d50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
35d60 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
35d70 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
35d80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a third argument.
35d90 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 ** to sqlite3_up
35da0 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 date_hook()..**
35db0 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c ^The second call
35dc0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 back argument is
35dd0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
35de0 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 INSERT], [SQLITE
35df0 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 _DELETE],.** or
35e00 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c [SQLITE_UPDATE],
35e10 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
35e20 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 e operation that
35e30 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c caused the call
35e40 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e back.** to be in
35e50 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 voked..** ^The t
35e60 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
35e70 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
35e80 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
35e90 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 n pointers to th
35ea0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e e.** database an
35eb0 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e d table name con
35ec0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 taining the affe
35ed0 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 cted row..** ^Th
35ee0 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b e final callback
35ef0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
35f00 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
35f10 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 row..** ^In the
35f20 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 case of an upda
35f30 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 te, this is the
35f40 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 [rowid] after th
35f50 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 e update takes p
35f60 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lace..**.** ^(Th
35f70 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 e update hook is
35f80 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 not invoked whe
35f90 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 n internal syste
35fa0 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 m tables are.**
35fb0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 modified (i.e. s
35fc0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 qlite_master and
35fd0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 sqlite_sequence
35fe0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 ).)^.**.** ^In t
35ff0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 he current imple
36000 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 mentation, the u
36010 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 pdate hook.** is
36020 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 not invoked whe
36030 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f n duplication ro
36040 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 ws are deleted b
36050 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 ecause of an.**
36060 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f [ON CONFLICT | O
36070 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 N CONFLICT REPLA
36080 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f CE] clause. ^No
36090 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 r is the update
360a0 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 hook.** invoked
360b0 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 when rows are de
360c0 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 leted using the
360d0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 [truncate optimi
360e0 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 zation]..** The
360f0 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e exceptions defin
36100 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 ed in this parag
36110 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 raph might chang
36120 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a e in a future.**
36130 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
36140 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 te..**.** The up
36150 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d date hook implem
36160 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f entation must no
36170 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
36180 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
36190 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
361a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
361b0 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 nvoked the updat
361c0 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 e hook. Any act
361d0 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 ions.** to modif
361e0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 y the database c
361f0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 onnection must b
36200 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c e deferred until
36210 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f after the.** co
36220 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 mpletion of the
36230 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
36240 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
36250 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 ered the update
36260 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 hook..** Note th
36270 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
36280 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
36290 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
362a0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
362b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
362c0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
362d0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
362e0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
362f0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 agraph..**.** ^T
36300 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 he sqlite3_updat
36310 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 e_hook(D,C,P) fu
36320 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e nction.** return
36330 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 s the P argument
36340 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f from the previo
36350 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 us call.** on th
36360 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
36370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 connection] D,
36380 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 or NULL for.** t
36390 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e he first call on
363a0 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c D..**.** See al
363b0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
363c0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 commit_hook()] a
363d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c nd [sqlite3_roll
363e0 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 back_hook()].**
363f0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 53 interfaces..*/.S
36400 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
36410 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
36420 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ook(. sqlite3*,
36430 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 . void(*)(void
36440 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e *,int ,char con
36450 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 st *,char const
36460 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 *,sqlite3_int64)
36470 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a ,. void*.);../*
36480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
36490 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
364a0 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 Shared Pager Cac
364b0 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 he.** KEYWORDS:
364c0 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a {shared cache}.*
364d0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
364e0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ine enables or d
364f0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 isables the shar
36500 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 ing of the datab
36510 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 ase cache.** and
36520 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 schema data str
36530 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 uctures between
36540 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36550 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f tion | connectio
36560 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 ns].** to the sa
36570 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 me database. Sha
36580 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 ring is enabled
36590 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 if the argument
365a0 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 is true.** and d
365b0 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 isabled if the a
365c0 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 rgument is false
365d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 .)^.**.** ^Cache
365e0 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 sharing is enab
365f0 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 led and disabled
36600 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 for an entire p
36610 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 rocess..** This
36620 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f is a change as o
36630 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
36640 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 3.5.0. In prior
36650 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
36660 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 ite,.** sharing
36670 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 was enabled or d
36680 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 isabled for each
36690 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 thread separate
366a0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ly..**.** ^(The
366b0 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f cache sharing mo
366c0 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 de set by this i
366d0 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 nterface effects
366e0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a all subsequent.
366f0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ** calls to [sql
36700 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
36710 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
36720 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
36730 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 open16()]..** Ex
36740 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 isting database
36750 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 connections cont
36760 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 inue use the sha
36770 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 ring mode.** tha
36780 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 t was in effect
36790 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 at the time they
367a0 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a were opened.)^.
367b0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 **.** ^(This rou
367c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 tine returns [SQ
367d0 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 LITE_OK] if shar
367e0 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 ed cache was ena
367f0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
36800 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
36810 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 . An [error cod
36820 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f e] is returned o
36830 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a therwise.)^.**.*
36840 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 * ^Shared cache
36850 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
36860 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 efault. But this
36870 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e might change in
36880 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 .** future relea
36890 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ses of SQLite.
368a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
368b0 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 t care about sha
368c0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 red.** cache set
368d0 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 ting should set
368e0 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a it explicitly..*
368f0 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 *.** See Also:
36900 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 [SQLite Shared-C
36910 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 ache Mode].*/.SQ
36920 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
36930 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
36940 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a ed_cache(int);..
36950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36960 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 Attempt To Free
36970 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a Heap Memory.**.*
36980 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
36990 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 elease_memory()
369a0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
369b0 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 ts to free N byt
369c0 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 es.** of heap me
369d0 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 mory by dealloca
369e0 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 ting non-essenti
369f0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
36a00 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 tions.** held by
36a10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 the database li
36a20 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 brary. Memory
36a30 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 used to cache da
36a40 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 tabase.** pages
36a50 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f to improve perfo
36a60 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 rmance is an exa
36a70 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 mple of non-esse
36a80 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a ntial memory..**
36a90 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 ^sqlite3_releas
36aa0 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 e_memory() retur
36ab0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
36ac0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 bytes actually
36ad0 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 freed,.** which
36ae0 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 might be more or
36af0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 less than the a
36b00 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e mount requested.
36b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
36b20 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
36b30 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e ) routine is a n
36b40 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a o-op returning z
36b50 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 ero.** if SQLite
36b60 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 is not compiled
36b70 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e with [SQLITE_EN
36b80 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 ABLE_MEMORY_MANA
36b90 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 GEMENT]..**.** S
36ba0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
36bb0 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 3_db_release_mem
36bc0 6f 72 79 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 ory()].*/.SQLITE
36bd0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
36be0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
36bf0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
36c00 49 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f I3REF: Free Memo
36c10 72 79 20 55 73 65 64 20 42 79 20 41 20 44 61 74 ry Used By A Dat
36c20 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
36c30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36c40 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d te3_db_release_m
36c50 65 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66 61 emory(D) interfa
36c60 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 ce attempts to f
36c70 72 65 65 20 61 73 20 6d 75 63 68 20 68 65 61 70 ree as much heap
36c80 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f .** memory as po
36c90 73 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61 ssible from data
36ca0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
36cb0 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a D. Unlike the.**
36cc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
36cd0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65 e_memory()] inte
36ce0 72 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65 rface, this inte
36cf0 72 66 61 63 65 20 69 73 20 65 66 66 65 63 74 20 rface is effect
36d00 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 even.** when the
36d10 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 n [SQLITE_ENABLE
36d20 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 _MEMORY_MANAGEME
36d30 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 NT] compile-time
36d40 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d option is.** om
36d50 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 itted..**.** See
36d60 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
36d70 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
36d80 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
36d90 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 int sqlite3_db_r
36da0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73 71 elease_memory(sq
36db0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
36dc0 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 CAPI3REF: Impose
36dd0 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 A Limit On Heap
36de0 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 Size.**.** ^The
36df0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 sqlite3_soft_he
36e00 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74 ap_limit64() int
36e10 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f erface sets and/
36e20 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a or queries the.*
36e30 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20 * soft limit on
36e40 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 the amount of he
36e50 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d ap memory that m
36e60 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 ay be allocated
36e70 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 by SQLite..** ^S
36e80 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f QLite strives to
36e90 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72 keep heap memor
36ea0 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65 y utilization be
36eb0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61 low the soft hea
36ec0 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65 p.** limit by re
36ed0 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 ducing the numbe
36ee0 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20 r of pages held
36ef0 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 in the page cach
36f00 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d e.** as heap mem
36f10 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f ory usages appro
36f20 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e aches the limit.
36f30 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65 .** ^The soft he
36f40 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66 ap limit is "sof
36f50 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20 t" because even
36f60 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74 though SQLite st
36f70 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a rives to stay.**
36f80 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74 below the limit
36f90 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64 , it will exceed
36fa0 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65 the limit rathe
36fb0 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a r than generate.
36fc0 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f ** an [SQLITE_NO
36fd0 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20 MEM] error. In
36fe0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
36ff0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
37000 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79 .** is advisory
37010 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 only..**.** ^Th
37020 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
37030 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 rom sqlite3_soft
37040 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 _heap_limit64()
37050 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a is the size of.*
37060 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 * the soft heap
37070 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74 limit prior to t
37080 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e 65 67 61 he call, or nega
37090 74 69 76 65 20 69 6e 20 74 68 65 20 63 61 73 65 tive in the case
370a0 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e of an.** error.
370b0 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 ^If the argume
370c0 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 nt N is negative
370d0 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e .** then no chan
370e0 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68 ge is made to th
370f0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
37100 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 t. Hence, the c
37110 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f urrent.** size o
37120 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 f the soft heap
37130 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74 limit can be det
37140 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b ermined by invok
37150 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
37160 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
37170 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 () with a negati
37180 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a ve argument..**.
37190 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d ** ^If the argum
371a0 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 ent N is zero th
371b0 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 en the soft heap
371c0 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c limit is disabl
371d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ed..**.** ^(The
371e0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
371f0 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 is not enforced
37200 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 in the current i
37210 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
37220 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 if one or more
37230 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e of following con
37240 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65 ditions are true
37250 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
37260 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65 <li> The soft he
37270 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 ap limit is set
37280 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e to zero..** <li>
37290 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 Memory accounti
372a0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75 ng is disabled u
372b0 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 sing a combinati
372c0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 on of the.**
372d0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 [sqlite3_confi
372e0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
372f0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e G_MEMSTATUS],...
37300 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 ) start-time opt
37310 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ion and.**
37320 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 the [SQLITE_DEFA
37330 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 ULT_MEMSTATUS] c
37340 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
37350 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 on..** <li> An a
37360 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 lternative page
37370 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
37380 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 tion is specifie
37390 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 d using.**
373a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
373b0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
373c0 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a PCACHE2],...)..*
373d0 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20 * <li> The page
373e0 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 cache allocates
373f0 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d from its own mem
37400 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 ory pool supplie
37410 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71 d.** by [sq
37420 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
37430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
37440 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 ECACHE],...) rat
37450 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 her than.**
37460 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a from the heap..
37470 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
37480 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 Beginning with
37490 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
374a0 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68 .7.3, the soft h
374b0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 eap limit is enf
374c0 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c orced.** regardl
374d0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
374e0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 r not the [SQLIT
374f0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f E_ENABLE_MEMORY_
37500 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 MANAGEMENT].** c
37510 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
37520 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 on is invoked.
37530 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 With [SQLITE_ENA
37540 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 BLE_MEMORY_MANAG
37550 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 EMENT],.** the s
37560 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
37570 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 s enforced on ev
37580 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ery memory alloc
37590 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a ation. Without.
375a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
375b0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d E_MEMORY_MANAGEM
375c0 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 ENT], the soft h
375d0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c eap limit is onl
375e0 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 y enforced.** wh
375f0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c en memory is all
37600 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61 ocated by the pa
37610 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69 ge cache. Testi
37620 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74 ng suggests that
37630 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 because.** the
37640 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68 page cache is th
37650 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 e predominate me
37660 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c mory user in SQL
37670 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 ite, most.** app
37680 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 lications will a
37690 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20 chieve adequate
376a0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
376b0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 enforcement with
376c0 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f out.** the use o
376d0 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 f [SQLITE_ENABLE
376e0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 _MEMORY_MANAGEME
376f0 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 NT]..**.** The c
37700 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 ircumstances und
37710 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20 er which SQLite
37720 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 will enforce the
37730 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
37740 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 may.** changes
37750 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
37760 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
37770 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
37780 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
37790 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
377a0 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 t64(sqlite3_int6
377b0 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4 N);../*.** CAP
377c0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 I3REF: Deprecate
377d0 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 d Soft Heap Limi
377e0 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 t Interface.** D
377f0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 EPRECATED.**.**
37800 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63 This is a deprec
37810 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 ated version of
37820 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 the [sqlite3_sof
37830 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 t_heap_limit64()
37840 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 ].** interface.
37850 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
37860 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 provided for hi
37870 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 storical compati
37880 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 bility.** only.
37890 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 All new applica
378a0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 tions should use
378b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
378c0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
378d0 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64()] interface
378e0 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 rather than this
378f0 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f one..*/.SQLITE_
37900 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
37910 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 CATED void sqlit
37920 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
37930 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a it(int N);.../*.
37940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 ** CAPI3REF: Ext
37950 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 ract Metadata Ab
37960 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 out A Column Of
37970 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 A Table.**.** ^T
37980 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
37990 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f rns metadata abo
379a0 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f ut a specific co
379b0 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 lumn of a specif
379c0 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 ic.** database t
379d0 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 able accessible
379e0 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 using the [datab
379f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
37a00 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 handle.** passed
37a10 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 as the first fu
37a20 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
37a30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 .**.** ^The colu
37a40 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 mn is identified
37a50 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 by the second,
37a60 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 third and fourth
37a70 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a parameters to.*
37a80 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e * this function.
37a90 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
37aa0 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 ameter is either
37ab0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
37ac0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e database.** (i.
37ad0 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 e. "main", "temp
37ae0 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 ", or an attache
37af0 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 d database) cont
37b00 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 aining the speci
37b10 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 fied.** table or
37b20 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 NULL. ^If it is
37b30 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 NULL, then all
37b40 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
37b50 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a es are searched.
37b60 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 ** for the table
37b70 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 using the same
37b80 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 algorithm used b
37b90 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 y the database e
37ba0 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f ngine to.** reso
37bb0 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 lve unqualified
37bc0 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 table references
37bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
37be0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 rd and fourth pa
37bf0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 rameters to this
37c00 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 function are th
37c10 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 e table and colu
37c20 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 mn.** name of th
37c30 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e e desired column
37c40 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 , respectively.
37c50 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 Neither of these
37c60 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d parameters.** m
37c70 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ay be NULL..**.*
37c80 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 * ^Metadata is r
37c90 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 eturned by writi
37ca0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 ng to the memory
37cb0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 locations passe
37cc0 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 d as the 5th.**
37cd0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 and subsequent p
37ce0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 arameters to thi
37cf0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 s function. ^Any
37d00 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 of these argume
37d10 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 nts may be.** NU
37d20 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 LL, in which cas
37d30 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 e the correspond
37d40 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d ing element of m
37d50 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 etadata is omitt
37d60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f ed..**.** ^(<blo
37d70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
37d80 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
37d90 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d * <tr><th> Param
37da0 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 eter <th> Output
37db0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 <br>Type <th> D
37dc0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a escription.**.**
37dd0 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 <tr><td> 5th <t
37de0 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c d> const char* <
37df0 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a td> Data type.**
37e00 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 <tr><td> 6th <t
37e10 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c d> const char* <
37e20 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 td> Name of defa
37e30 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ult collation se
37e40 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 quence.** <tr><t
37e50 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 7th <td> int
37e60 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
37e70 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 e if column has
37e80 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 a NOT NULL const
37e90 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 raint.** <tr><td
37ea0 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 > 8th <td> int
37eb0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 <td> True
37ec0 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 if column is pa
37ed0 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 rt of the PRIMAR
37ee0 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 Y KEY.** <tr><td
37ef0 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 > 9th <td> int
37f00 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 <td> True
37f10 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 if column is [A
37f20 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a UTOINCREMENT].**
37f30 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 </table>.** </b
37f40 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a lockquote>)^.**.
37f50 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 ** ^The memory p
37f60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
37f70 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 character point
37f80 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 ers returned for
37f90 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 the.** declarat
37fa0 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c ion type and col
37fb0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 lation sequence
37fc0 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e is valid only un
37fd0 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 til the next.**
37fe0 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 call to any SQLi
37ff0 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e te API function.
38000 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 .**.** ^If the s
38010 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 pecified table i
38020 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 s actually a vie
38030 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 w, an [error cod
38040 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
38050 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 **.** ^If the sp
38060 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 ecified column i
38070 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 s "rowid", "oid"
38080 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e or "_rowid_" an
38090 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 d an.** [INTEGER
380a0 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f PRIMARY KEY] co
380b0 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 lumn has been ex
380c0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
380d0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 d, then the outp
380e0 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 ut.** parameters
380f0 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 are set for the
38100 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c explicitly decl
38110 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 ared column. ^(I
38120 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a f there is no.**
38130 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c explicitly decl
38140 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 ared [INTEGER PR
38150 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d IMARY KEY] colum
38160 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 n, then the outp
38170 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 ut.** parameters
38180 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c are set as foll
38190 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e ows:.**.** <pre>
381a0 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 .** data typ
381b0 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 e: "INTEGER".**
381c0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 collation se
381d0 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 quence: "BINARY"
381e0 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c .** not null
381f0 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 : 0.** prima
38200 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 ry key: 1.**
38210 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a auto increment:
38220 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 0.** </pre>)^.*
38230 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 *.** ^(This func
38240 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e tion may load on
38250 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 e or more schema
38260 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 s from database
38270 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 files. If an.**
38280 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
38290 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 ing this process
382a0 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 , or if the requ
382b0 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 ested table or c
382c0 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 olumn.** cannot
382d0 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 be found, an [er
382e0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
382f0 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 urned and an err
38300 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a or message left.
38310 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 ** in the [datab
38320 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
38330 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 (to be retrieved
38340 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 using sqlite3_e
38350 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a rrmsg()).)^.**.*
38360 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f * ^This API is o
38370 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
38380 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
38390 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
383a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
383b0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 ABLE_COLUMN_META
383c0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 DATA] C-preproce
383d0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 ssor symbol defi
383e0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ned..*/.SQLITE_A
383f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 PI int sqlite3_t
38400 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 able_column_meta
38410 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 data(. sqlite3
38420 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
38430 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f /* Connectio
38440 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f n handle */. co
38450 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d nst char *zDbNam
38460 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 e, /* Dat
38470 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 abase name or NU
38480 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 LL */. const ch
38490 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 ar *zTableName,
384a0 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d /* Table nam
384b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
384c0 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 r *zColumnName,
384d0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d /* Column nam
384e0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 e */. char cons
384f0 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 t **pzDataType,
38500 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 /* OUTPUT: De
38510 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 clared data type
38520 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 */. char const
38530 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 **pzCollSeq,
38540 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c /* OUTPUT: Col
38550 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 lation sequence
38560 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 name */. int *p
38570 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 NotNull,
38580 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
38590 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c True if NOT NUL
385a0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 L constraint exi
385b0 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 sts */. int *pP
385c0 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 rimaryKey,
385d0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 /* OUTPUT:
385e0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 True if column p
385f0 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 art of PK */. i
38600 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 nt *pAutoinc
38610 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 /* OU
38620 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f TPUT: True if co
38630 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 lumn is auto-inc
38640 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a rement */.);../*
38650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f .** CAPI3REF: Lo
38660 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a ad An Extension.
38670 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
38680 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 rface loads an S
38690 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 QLite extension
386a0 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 library from the
386b0 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a named file..**.
386c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
386d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
386e0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
386f0 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a pts to load an.*
38700 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 * SQLite extensi
38710 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 on library conta
38720 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 ined in the file
38730 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 zFile..**.** ^T
38740 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 he entry point i
38750 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 s zProc..** ^zPr
38760 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 oc may be 0, in
38770 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e which case the n
38780 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 ame of the entry
38790 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c point.** defaul
387a0 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 ts to "sqlite3_e
387b0 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a xtension_init"..
387c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
387d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
387e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
387f0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b ns.** [SQLITE_OK
38800 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 ] on success and
38810 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
38820 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 if something goe
38830 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 s wrong..** ^If
38840 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
38850 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 and pzErrMsg is
38860 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a not 0, then the.
38870 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 ** [sqlite3_load
38880 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e _extension()] in
38890 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 terface shall at
388a0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c tempt to.** fill
388b0 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 *pzErrMsg with
388c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 error message te
388d0 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d xt stored in mem
388e0 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 ory.** obtained
388f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
38900 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c lloc()]. The cal
38910 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a ling function.**
38920 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 should free thi
38930 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c s memory by call
38940 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
38950 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 e()]..**.** ^Ext
38960 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d ension loading m
38970 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 ust be enabled u
38980 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
38990 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
389a0 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 ension()] prior
389b0 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 to calling this
389c0 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 API,.** otherwis
389d0 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 e an error will
389e0 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a be returned..**.
389f0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
38a00 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 [load_extension(
38a10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
38a20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
38a30 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f nt sqlite3_load_
38a40 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c extension(. sql
38a50 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
38a60 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 /* Load the e
38a70 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 xtension into th
38a80 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e is database conn
38a90 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 ection */. cons
38aa0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 t char *zFile,
38ab0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
38ac0 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 shared library
38ad0 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e containing exten
38ae0 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 sion */. const
38af0 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 char *zProc,
38b00 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 /* Entry point.
38b10 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 Derived from zF
38b20 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 ile if 0 */. ch
38b30 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 ar **pzErrMsg
38b40 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 /* Put error
38b50 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 message here if
38b60 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a not 0 */.);../*
38b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
38b80 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
38b90 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e Extension Loadin
38ba0 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e g.**.** ^So as n
38bb0 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 ot to open secur
38bc0 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 ity holes in old
38bd0 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 er applications
38be0 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 that are.** unpr
38bf0 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 epared to deal w
38c00 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f ith extension lo
38c10 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 ading, and as a
38c20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 means of disabli
38c30 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 ng.** extension
38c40 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 loading while ev
38c50 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e aluating user-en
38c60 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 tered SQL, the f
38c70 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 ollowing API.**
38c80 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 is provided to t
38c90 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 urn the [sqlite3
38ca0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
38cb0 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 )] mechanism on
38cc0 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e and off..**.** ^
38cd0 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e Extension loadin
38ce0 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 g is off by defa
38cf0 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 ult. See ticket
38d00 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 #1863..** ^Call
38d10 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 the sqlite3_enab
38d20 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
38d30 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 n() routine with
38d40 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 onoff==1.** to
38d50 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c turn extension l
38d60 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 oading on and ca
38d70 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 ll it with onoff
38d80 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 ==0 to turn.** i
38d90 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e t back off again
38da0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
38db0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 int sqlite3_enab
38dc0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
38dd0 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 n(sqlite3 *db, i
38de0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a nt onoff);../*.*
38df0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f * CAPI3REF: Auto
38e00 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53 matically Load S
38e10 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 tatically Linked
38e20 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a Extensions.**.*
38e30 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 * ^This interfac
38e40 65 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e e causes the xEn
38e50 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74 tryPoint() funct
38e60 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ion to be invoke
38e70 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65 d for.** each ne
38e80 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e w [database conn
38e90 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20 ection] that is
38ea0 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64 created. The id
38eb0 65 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a ea here is that.
38ec0 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 ** xEntryPoint()
38ed0 20 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f is the entry po
38ee0 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63 int for a static
38ef0 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69 ally linked SQLi
38f00 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 te extension.**
38f10 74 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75 that is to be au
38f20 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64 tomatically load
38f30 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 ed into all new
38f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
38f50 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 ions..**.** ^(Ev
38f60 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75 en though the fu
38f70 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65 nction prototype
38f80 20 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74 shows that xEnt
38f90 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a ryPoint() takes.
38fa0 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 ** no arguments
38fb0 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64 and returns void
38fc0 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 , SQLite invokes
38fd0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 xEntryPoint() w
38fe0 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67 ith three.** arg
38ff0 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63 uments and expec
39000 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72 ts and integer r
39010 65 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20 esult as if the
39020 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 signature of the
39030 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 .** entry point
39040 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 where as follows
39050 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
39060 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 ote><pre>.** &nb
39070 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50 sp; int xEntryP
39080 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 oint(.**
39090 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a sqlite3 *db,.
390a0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e ** con
390b0 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d st char **pzErrM
390c0 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 sg,.**
390d0 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 const struct sq
390e0 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e lite3_api_routin
390f0 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e es *pThunk.** &n
39100 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 bsp; );.** </pr
39110 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
39120 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 ^.**.** If the x
39130 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69 EntryPoint routi
39140 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e ne encounters an
39150 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c error, it shoul
39160 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67 d make *pzErrMsg
39170 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 .** point to an
39180 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f appropriate erro
39190 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69 r message (obtai
391a0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
391b0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 3_mprintf()]).**
391c0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61 and return an a
391d0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
391e0 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74 r code]. ^SQLit
391f0 65 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a e ensures that *
39200 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e pzErrMsg.** is N
39210 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 ULL before calli
39220 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 ng the xEntryPoi
39230 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77 nt(). ^SQLite w
39240 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 ill invoke.** [s
39250 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f qlite3_free()] o
39260 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65 n *pzErrMsg afte
39270 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 r xEntryPoint()
39280 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e returns. ^If an
39290 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 y.** xEntryPoint
392a0 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 () returns an er
392b0 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 ror, the [sqlite
392c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
392d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a te3_open16()],.*
392e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 * or [sqlite3_op
392f0 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68 en_v2()] call th
39300 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 at provoked the
39310 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69 xEntryPoint() wi
39320 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e ll fail..**.** ^
39330 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
39340 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58 auto_extension(X
39350 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20 ) with an entry
39360 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20 point X that is
39370 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 already.** on th
39380 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61 e list of automa
39390 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 tic extensions i
393a0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
393b0 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f op. ^No entry po
393c0 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63 int.** will be c
393d0 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 alled more than
393e0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61 once for each da
393f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
39400 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64 n that is opened
39410 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
39420 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 : [sqlite3_reset
39430 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 _auto_extension(
39440 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
39450 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 I int sqlite3_au
39460 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 to_extension(voi
39470 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 d (*xEntryPoint)
39480 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 (void));../*.**
39490 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
394a0 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 Automatic Extens
394b0 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a ion Loading.**.*
394c0 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 * ^This interfac
394d0 65 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 61 e disables all a
394e0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
394f0 6f 6e 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a ons previously.*
39500 2a 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 * registered usi
39510 6e 67 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f ng [sqlite3_auto
39520 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a _extension()]..*
39530 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
39540 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f d sqlite3_reset_
39550 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 auto_extension(v
39560 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 oid);../*.** The
39570 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 interface to th
39580 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
39590 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 mechanism is cur
395a0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
395b0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 d.** to be exper
395c0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e imental. The in
395d0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 terface might ch
395e0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 ange in incompat
395f0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 ible ways..** If
39600 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c this is a probl
39610 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e em for you, do n
39620 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 ot use the inter
39630 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d face at this tim
39640 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
39650 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
39660 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c mechanism stabil
39670 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 izes, we will de
39680 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 clare the.** int
39690 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 erface fixed, su
396a0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e pport it indefin
396b0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 itely, and remov
396c0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a e this comment..
396d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 */../*.** Struct
396e0 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 ures used by the
396f0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 virtual table i
39700 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 nterface.*/.type
39710 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
39720 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f e3_vtab sqlite3_
39730 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 vtab;.typedef st
39740 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
39750 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f ex_info sqlite3_
39760 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 index_info;.type
39770 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
39780 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 e3_vtab_cursor s
39790 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
397a0 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 or;.typedef stru
397b0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c ct sqlite3_modul
397c0 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 e sqlite3_module
397d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
397e0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 F: Virtual Table
397f0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
39800 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 RDS: sqlite3_mod
39810 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 ule {virtual tab
39820 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a le module}.**.**
39830 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c This structure,
39840 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 sometimes calle
39850 64 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 d a "virtual tab
39860 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 le module", .**
39870 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c defines the impl
39880 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 ementation of a
39890 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
398a0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 . .** This stru
398b0 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d cture consists m
398c0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
398d0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
398e0 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 .**.** ^A virtua
398f0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 l table module i
39900 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c s created by fil
39910 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 ling in a persis
39920 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 tent.** instance
39930 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
39940 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 re and passing a
39950 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 pointer to that
39960 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 instance.** to
39970 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
39980 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 module()] or [sq
39990 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
399a0 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 ule_v2()]..** ^T
399b0 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 he registration
399c0 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e remains valid un
399d0 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 til it is replac
399e0 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e ed by a differen
399f0 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 t.** module or u
39a00 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 ntil the [databa
39a10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 se connection] c
39a20 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 loses. The cont
39a30 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 ent.** of this s
39a40 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f tructure must no
39a50 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 t change while i
39a60 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 t is registered
39a70 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 with.** any data
39a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
39a90 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
39aa0 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
39ab0 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
39ac0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
39ad0 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
39ae0 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
39af0 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
39b00 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
39b10 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
39b20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
39b30 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
39b40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
39b50 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
39b60 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
39b70 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
39b80 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
39b90 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
39ba0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
39bb0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
39bc0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
39bd0 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
39be0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
39bf0 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
39c00 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
39c10 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
39c20 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
39c30 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
39c40 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
39c50 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
39c60 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
39c70 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
39c80 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
39c90 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
39ca0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
39cb0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
39cc0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
39cd0 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
39ce0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
39cf0 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
39d00 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
39d10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
39d20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
39d30 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
39d40 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
39d50 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
39d60 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
39d70 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
39d80 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
39d90 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
39da0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
39db0 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
39dc0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
39dd0 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
39de0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
39df0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
39e00 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 pRowid);. int (
39e10 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 *xUpdate)(sqlite
39e20 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 3_vtab *, int, s
39e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c qlite3_value **,
39e40 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
39e50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 );. int (*xBegi
39e60 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
39e70 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
39e80 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
39e90 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
39ea0 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 int (*xCommit)(s
39eb0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
39ec0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f ab);. int (*xRo
39ed0 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f llback)(sqlite3_
39ee0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
39ef0 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 int (*xFindFunct
39f00 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ion)(sqlite3_vta
39f10 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 b *pVtab, int nA
39f20 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a rg, const char *
39f30 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 zName,.
39f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
39f50 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 id (**pxFunc)(sq
39f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
39f70 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
39f80 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 **),.
39f90 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
39fa0 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 **ppArg);. int
39fb0 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 (*xRename)(sqli
39fc0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c te3_vtab *pVtab,
39fd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 const char *zNe
39fe0 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74 w);. /* The met
39ff0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
3a000 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 n version 1 of t
3a010 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 he sqlite_module
3a020 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a object. Those .
3a030 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 ** below are f
3a040 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 or version 2 and
3a050 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69 greater. */. i
3a060 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 nt (*xSavepoint)
3a070 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
3a080 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e VTab, int);. in
3a090 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 t (*xRelease)(sq
3a0a0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
3a0b0 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 b, int);. int (
3a0c0 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 *xRollbackTo)(sq
3a0d0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
3a0e0 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a b, int);.};../*.
3a0f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
3a100 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 tual Table Index
3a110 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a ing Information.
3a120 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
3a130 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a ite3_index_info.
3a140 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
3a150 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 3_index_info str
3a160 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 ucture and its s
3a170 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 ubstructures is
3a180 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 used as part.**
3a190 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 of the [virtual
3a1a0 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 table] interface
3a1b0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f to.** pass info
3a1c0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 rmation into and
3a1d0 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 receive the rep
3a1e0 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 ly from the [xBe
3a1f0 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 stIndex].** meth
3a200 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c od of a [virtual
3a210 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 table module].
3a220 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 The fields unde
3a230 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 r **Inputs** are
3a240 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 the.** inputs t
3a250 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 o xBestIndex and
3a260 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 are read-only.
3a270 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 xBestIndex inse
3a280 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c rts its.** resul
3a290 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 ts into the **Ou
3a2a0 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a tputs** fields..
3a2b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e **.** ^(The aCon
3a2c0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
3a2d0 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c records WHERE cl
3a2e0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
3a2f0 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a of the form:.**
3a300 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
3a310 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f column OP expr</
3a320 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
3a330 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c * where OP is =,
3a340 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 <, <=, &g
3a350 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 t;, or >=.)^
3a360 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 ^(The particula
3a370 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a r operator is.**
3a380 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 stored in aCons
3a390 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e traint[].op usin
3a3a0 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 g one of the.**
3a3b0 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f [SQLITE_INDEX_CO
3a3c0 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 NSTRAINT_EQ | SQ
3a3d0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
3a3e0 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 RAINT_ values].)
3a3f0 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 ^.** ^(The index
3a400 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 of the column i
3a410 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 s stored in.** a
3a420 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f Constraint[].iCo
3a430 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 lumn.)^ ^(aCons
3a440 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 traint[].usable
3a450 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a is TRUE if the.*
3a460 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 * expr on the ri
3a470 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 ght-hand side ca
3a480 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 n be evaluated (
3a490 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e and thus the con
3a4a0 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 straint.** is us
3a4b0 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 able) and false
3a4c0 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a if it cannot.)^.
3a4d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d **.** ^The optim
3a4e0 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c izer automatical
3a4f0 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 ly inverts terms
3a500 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 of the form "ex
3a510 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a pr OP column".**
3a520 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 and makes other
3a530 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 simplifications
3a540 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c to the WHERE cl
3a550 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d ause in an attem
3a560 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 pt to.** get as
3a570 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 many WHERE claus
3a580 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 e terms into the
3a590 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 form shown abov
3a5a0 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a e as possible..*
3a5b0 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 * ^The aConstrai
3a5c0 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 nt[] array only
3a5d0 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c reports WHERE cl
3a5e0 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 ause terms that
3a5f0 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 are.** relevant
3a600 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 to the particula
3a610 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
3a620 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a being queried..*
3a630 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f *.** ^Informatio
3a640 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 n about the ORDE
3a650 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 R BY clause is s
3a660 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 tored in aOrderB
3a670 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 y[]..** ^Each te
3a680 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 rm of aOrderBy r
3a690 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 ecords a column
3a6a0 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 of the ORDER BY
3a6b0 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 clause..**.** Th
3a6c0 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d e [xBestIndex] m
3a6d0 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 ethod must fill
3a6e0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
3a6f0 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 [] with informat
3a700 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 ion.** about wha
3a710 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
3a720 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e pass to xFilter.
3a730 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e ^If argvIndex>
3a740 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 0 then.** the ri
3a750 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 ght-hand side of
3a760 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
3a770 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d ng aConstraint[]
3a780 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a is evaluated.**
3a790 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 and becomes the
3a7a0 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e argvIndex-th en
3a7b0 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 try in argv. ^(
3a7c0 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 If aConstraintUs
3a7d0 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 age[].omit.** is
3a7e0 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 true, then the
3a7f0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 constraint is as
3a800 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c sumed to be full
3a810 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 y handled by the
3a820 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c .** virtual tabl
3a830 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 e and is not che
3a840 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 cked again by SQ
3a850 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 Lite.)^.**.** ^T
3a860 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 he idxNum and id
3a870 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 xPtr values are
3a880 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 recorded and pas
3a890 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 sed into the.**
3a8a0 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 [xFilter] method
3a8b0 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 ..** ^[sqlite3_f
3a8c0 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 ree()] is used t
3a8d0 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 o free idxPtr if
3a8e0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
3a8f0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 needToFreeIdxPtr
3a900 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 is true..**.**
3a910 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 ^The orderByCons
3a920 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 umed means that
3a930 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 output from [xFi
3a940 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 lter]/[xNext] wi
3a950 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 ll occur in.** t
3a960 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 he correct order
3a970 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 to satisfy the
3a980 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 ORDER BY clause
3a990 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 so that no separ
3a9a0 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 ate.** sorting s
3a9b0 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e tep is required.
3a9c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 .**.** ^The esti
3a9d0 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 matedCost value
3a9e0 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f is an estimate o
3a9f0 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f f the cost of do
3aa00 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 ing the.** parti
3aa10 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 cular lookup. A
3aa20 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 full scan of a
3aa30 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 table with N ent
3aa40 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 ries should have
3aa50 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e .** a cost of N.
3aa60 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 A binary searc
3aa70 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 h of a table of
3aa80 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 N entries should
3aa90 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 have a.** cost
3aaa0 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 of approximately
3aab0 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 log(N)..*/.stru
3aac0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
3aad0 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 _info {. /* Inp
3aae0 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f uts */. int nCo
3aaf0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
3ab00 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
3ab10 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e entries in aCon
3ab20 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 straint */. str
3ab30 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
3ab40 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 x_constraint {.
3ab50 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b int iColumn;
3ab60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3ab70 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d Column on left-
3ab80 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e hand side of con
3ab90 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 straint */.
3aba0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 unsigned char op
3abb0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e ; /* Con
3abc0 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 straint operator
3abd0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 */. unsigne
3abe0 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 d char usable;
3abf0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 /* True if th
3ac00 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 is constraint is
3ac10 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 usable */.
3ac20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b int iTermOffset;
3ac30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 /* Use
3ac40 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 d internally - x
3ac50 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 BestIndex should
3ac60 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a ignore */. } *
3ac70 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 aConstraint;
3ac80 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 /* Table
3ac90 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 of WHERE clause
3aca0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a constraints */.
3acb0 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 int nOrderBy;
3acc0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3acd0 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 Number of terms
3ace0 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 in the ORDER BY
3acf0 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 clause */. stru
3ad00 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
3ad10 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 _orderby {.
3ad20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 int iColumn;
3ad30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c /* Col
3ad40 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 umn number */.
3ad50 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
3ad60 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 desc; /*
3ad70 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 True for DESC.
3ad80 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a False for ASC. *
3ad90 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b /. } *aOrderBy;
3ada0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3adb0 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 * The ORDER BY c
3adc0 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 lause */. /* Ou
3add0 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 tputs */. struc
3ade0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
3adf0 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 constraint_usage
3ae00 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 {. int argvI
3ae10 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 ndex;
3ae20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 /* if >0, constr
3ae30 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 aint is part of
3ae40 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 argv to xFilter
3ae50 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 */. unsigned
3ae60 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 char omit;
3ae70 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 /* Do not code a
3ae80 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 test for this c
3ae90 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d onstraint */. }
3aea0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 *aConstraintUsa
3aeb0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d ge;. int idxNum
3aec0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
3aed0 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 /* Number used
3aee0 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 to identify the
3aef0 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 index */. char
3af00 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 *idxStr;
3af10 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c /* String,
3af20 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e possibly obtain
3af30 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
3af40 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 malloc */. int
3af50 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 needToFreeIdxStr
3af60 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 ; /* Free i
3af70 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 dxStr using sqli
3af80 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 te3_free() if tr
3af90 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 ue */. int orde
3afa0 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 rByConsumed;
3afb0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 /* True if ou
3afc0 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 tput is already
3afd0 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 ordered */. dou
3afe0 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 ble estimatedCos
3aff0 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d t; /* Estim
3b000 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 ated cost of usi
3b010 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f ng this index */
3b020 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
3b030 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 REF: Virtual Tab
3b040 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 le Constraint Op
3b050 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a erator Codes.**.
3b060 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 ** These macros
3b070 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f defined the allo
3b080 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 wed values for t
3b090 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 he.** [sqlite3_i
3b0a0 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 ndex_info].aCons
3b0b0 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c traint[].op fiel
3b0c0 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 d. Each value r
3b0d0 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 epresents.** an
3b0e0 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 operator that is
3b0f0 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 part of a const
3b100 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 raint term in th
3b110 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f e wHERE clause o
3b120 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 f.** a query tha
3b130 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 t uses a [virtua
3b140 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 l table]..*/.#de
3b150 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
3b160 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 X_CONSTRAINT_EQ
3b170 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
3b180 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
3b190 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 AINT_GT 4.#de
3b1a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
3b1b0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 X_CONSTRAINT_LE
3b1c0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
3b1d0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
3b1e0 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 AINT_LT 16.#d
3b1f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
3b200 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 EX_CONSTRAINT_GE
3b210 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 32.#define S
3b220 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
3b230 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a TRAINT_MATCH 64.
3b240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3b250 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 Register A Virt
3b260 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d ual Table Implem
3b270 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e entation.**.** ^
3b280 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
3b290 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 re used to regis
3b2a0 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 ter a new [virtu
3b2b0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
3b2c0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c name..** ^Modul
3b2d0 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 e names must be
3b2e0 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 registered befor
3b2f0 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20 e.** creating a
3b300 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 new [virtual tab
3b310 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f le] using the mo
3b320 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20 dule and before
3b330 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 using a.** preex
3b340 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 isting [virtual
3b350 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d table] for the m
3b360 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 odule..**.** ^Th
3b370 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 e module name is
3b380 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 registered on t
3b390 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
3b3a0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
3b3b0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 ed.** by the fir
3b3c0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e st parameter. ^
3b3d0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
3b3e0 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 module is given
3b3f0 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e by the .** secon
3b400 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 d parameter. ^T
3b410 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
3b420 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
3b430 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d to.** the implem
3b440 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
3b450 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d [virtual table m
3b460 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 odule]. ^The f
3b470 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 ourth.** paramet
3b480 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
3b490 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 ry client data p
3b4a0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 ointer that is p
3b4b0 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a assed through.**
3b4c0 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 into the [xCrea
3b4d0 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 te] and [xConnec
3b4e0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 t] methods of th
3b4f0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
3b500 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 module.** when a
3b510 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 new virtual tab
3b520 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 le is be being c
3b530 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 reated or reinit
3b540 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ialized..**.** ^
3b550 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 The sqlite3_crea
3b560 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 te_module_v2() i
3b570 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66 nterface has a f
3b580 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 ifth parameter w
3b590 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
3b5a0 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 nter to a destru
3b5b0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c ctor for the pCl
3b5c0 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 ientData. ^SQLi
3b5d0 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b te will.** invok
3b5e0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
3b5f0 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 function (if it
3b600 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 is not NULL) wh
3b610 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 en SQLite.** no
3b620 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 longer needs the
3b630 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 pClientData poi
3b640 6e 74 65 72 2e 20 20 5e 54 68 65 20 64 65 73 74 nter. ^The dest
3b650 72 75 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73 6f ructor will also
3b660 0a 2a 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20 69 .** be invoked i
3b670 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 f the call to sq
3b680 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
3b690 75 6c 65 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a ule_v2() fails..
3b6a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
3b6b0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a create_module().
3b6c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
3b6d0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 equivalent to sq
3b6e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
3b6f0 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 ule_v2() with a
3b700 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 NULL.** destruct
3b710 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 or..*/.SQLITE_AP
3b720 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 I int sqlite3_cr
3b730 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 eate_module(. s
3b740 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
3b750 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
3b760 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ite connection t
3b770 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c o register modul
3b780 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 e with */. cons
3b790 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 t char *zName,
3b7a0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
3b7b0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a f the module */.
3b7c0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f const sqlite3_
3b7d0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 module *p, /*
3b7e0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 Methods for the
3b7f0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 module */. void
3b800 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 *pClientData
3b810 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 /* Client
3b820 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 data for xCreat
3b830 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b e/xConnect */.);
3b840 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
3b850 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
3b860 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 odule_v2(. sqli
3b870 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
3b880 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
3b890 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
3b8a0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
3b8b0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
3b8c0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
3b8d0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
3b8e0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
3b8f0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
3b900 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 ule *p, /* Met
3b910 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
3b920 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 ule */. void *p
3b930 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 ClientData,
3b940 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
3b950 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
3b960 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 Connect */. voi
3b970 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
3b980 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c d*) /* Modul
3b990 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e e destructor fun
3b9a0 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a ction */.);../*.
3b9b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
3b9c0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 tual Table Insta
3b9d0 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 nce Object.** KE
3b9e0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
3b9f0 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 vtab.**.** Every
3ba00 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
3ba10 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e module] implemen
3ba20 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 tation uses a su
3ba30 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 bclass.** of thi
3ba40 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 s object to desc
3ba50 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 ribe a particula
3ba60 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 r instance.** of
3ba70 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 the [virtual ta
3ba80 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 ble]. Each subc
3ba90 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 lass will.** be
3baa0 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 tailored to the
3bab0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
3bac0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 f the module imp
3bad0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 lementation..**
3bae0 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 The purpose of t
3baf0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 his superclass i
3bb00 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 s to define cert
3bb10 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 ain fields that
3bb20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f are.** common to
3bb30 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c all module impl
3bb40 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a ementations..**.
3bb50 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c ** ^Virtual tabl
3bb60 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 es methods can s
3bb70 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 et an error mess
3bb80 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 age by assigning
3bb90 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 a.** string obt
3bba0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
3bbb0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 te3_mprintf()] t
3bbc0 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 o zErrMsg. The
3bbd0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a method should.**
3bbe0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 take care that
3bbf0 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 any prior string
3bc00 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 is freed by a c
3bc10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
3bc20 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 free()].** prior
3bc30 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 to assigning a
3bc40 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 new string to zE
3bc50 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 rrMsg. ^After t
3bc60 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
3bc70 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 .** is delivered
3bc80 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e up to the clien
3bc90 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 t application, t
3bca0 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
3bcb0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
3bcc0 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 ** freed by sqli
3bcd0 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 te3_free() and t
3bce0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 he zErrMsg field
3bcf0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e will be zeroed.
3bd00 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
3bd10 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 e3_vtab {. cons
3bd20 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
3bd30 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 *pModule; /* T
3bd40 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 he module for th
3bd50 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 is virtual table
3bd60 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 */. int nRef;
3bd70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3bd80 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 /* NO LONG
3bd90 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 ER USED */. cha
3bda0 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 r *zErrMsg;
3bdb0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3bdc0 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 Error message fr
3bdd0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e om sqlite3_mprin
3bde0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 tf() */. /* Vir
3bdf0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
3be00 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 mentations will
3be10 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 typically add ad
3be20 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
3be30 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
3be40 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
3be50 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 able Cursor Obje
3be60 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
3be70 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
3be80 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 sor {virtual tab
3be90 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a le cursor}.**.**
3bea0 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 Every [virtual
3beb0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d table module] im
3bec0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 plementation use
3bed0 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 s a subclass of
3bee0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 the.** following
3bef0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 structure to de
3bf00 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 scribe cursors t
3bf10 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 hat point into t
3bf20 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 he.** [virtual t
3bf30 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 able] and are us
3bf40 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 ed.** to loop th
3bf50 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 rough the virtua
3bf60 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 l table. Cursor
3bf70 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
3bf80 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
3bf90 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e te3_module.xOpen
3bfa0 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 | xOpen] method
3bfb0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 of the module a
3bfc0 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 nd are destroyed
3bfd0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 .** by the [sqli
3bfe0 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 te3_module.xClos
3bff0 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 e | xClose] meth
3c000 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 od. Cursors are
3c010 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 used.** by the
3c020 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 [xFilter], [xNex
3c030 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f t], [xEof], [xCo
3c040 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 lumn], and [xRow
3c050 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f id] methods.** o
3c060 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 f the module. E
3c070 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 ach module imple
3c080 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 mentation will d
3c090 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e efine.** the con
3c0a0 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 tent of a cursor
3c0b0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 structure to su
3c0c0 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 it its own needs
3c0d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 ..**.** This sup
3c0e0 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 erclass exists i
3c0f0 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e n order to defin
3c100 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 e fields of the
3c110 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 cursor that.** a
3c120 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c re common to all
3c130 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
3c140 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
3c150 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
3c160 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 {. sqlite3_vtab
3c170 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a *pVtab; /*
3c180 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f Virtual table o
3c190 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f f this cursor */
3c1a0 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 . /* Virtual ta
3c1b0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
3c1c0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c ons will typical
3c1d0 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ly add additiona
3c1e0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a l fields */.};..
3c1f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3c200 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 Declare The Sche
3c210 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 ma Of A Virtual
3c220 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 Table.**.** ^The
3c230 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b [xCreate] and [
3c240 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 xConnect] method
3c250 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 s of a.** [virtu
3c260 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
3c270 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 call this inter
3c280 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 face.** to decla
3c290 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 re the format (t
3c2a0 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 he names and dat
3c2b0 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f atypes of the co
3c2c0 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 lumns) of.** the
3c2d0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
3c2e0 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a they implement..
3c2f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
3c300 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 t sqlite3_declar
3c310 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c e_vtab(sqlite3*,
3c320 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 const char *zSQ
3c330 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 L);../*.** CAPI3
3c340 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 REF: Overload A
3c350 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 Function For A V
3c360 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a irtual Table.**.
3c370 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62 ** ^(Virtual tab
3c380 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 les can provide
3c390 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c alternative impl
3c3a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 ementations of f
3c3b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e unctions.** usin
3c3c0 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 g the [xFindFunc
3c3d0 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 tion] method of
3c3e0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 the [virtual tab
3c3f0 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a le module]. .**
3c400 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 But global vers
3c410 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 ions of those fu
3c420 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 nctions.** must
3c430 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 exist in order t
3c440 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e o be overloaded.
3c450 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 )^.**.** ^(This
3c460 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 API makes sure a
3c470 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 global version
3c480 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 of a function wi
3c490 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
3c4a0 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 ** name and numb
3c4b0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 er of parameters
3c4c0 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 exists. If no
3c4d0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 such function ex
3c4e0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 ists.** before t
3c4f0 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 his API is calle
3c500 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f d, a new functio
3c510 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20 n is created.)^
3c520 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ^The implementa
3c530 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e tion.** of the n
3c540 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 ew function alwa
3c550 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 ys causes an exc
3c560 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 eption to be thr
3c570 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 own. So.** the
3c580 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 new function is
3c590 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 not good for any
3c5a0 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e thing by itself.
3c5b0 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 Its only.** pu
3c5c0 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 rpose is to be a
3c5d0 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e placeholder fun
3c5e0 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 ction that can b
3c5f0 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 e overloaded.**
3c600 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 by a [virtual ta
3c610 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ble]..*/.SQLITE_
3c620 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
3c630 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f overload_functio
3c640 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 n(sqlite3*, cons
3c650 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d t char *zFuncNam
3c660 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f e, int nArg);../
3c670 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 *.** The interfa
3c680 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 ce to the virtua
3c690 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 l-table mechanis
3c6a0 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 m defined above
3c6b0 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 (back up.** to a
3c6c0 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 comment remarka
3c6d0 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 bly similar to t
3c6e0 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 his one) is curr
3c6f0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 ently considered
3c700 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 .** to be experi
3c710 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 mental. The int
3c720 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 erface might cha
3c730 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 nge in incompati
3c740 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 ble ways..** If
3c750 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 this is a proble
3c760 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f m for you, do no
3c770 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 t use the interf
3c780 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 ace at this time
3c790 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
3c7a0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
3c7b0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 echanism stabili
3c7c0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 zes, we will dec
3c7d0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 lare the.** inte
3c7e0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 rface fixed, sup
3c7f0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 port it indefini
3c800 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 tely, and remove
3c810 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a this comment..*
3c820 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
3c830 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 F: A Handle To A
3c840 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b n Open BLOB.** K
3c850 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 EYWORDS: {BLOB h
3c860 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e andle} {BLOB han
3c870 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 dles}.**.** An i
3c880 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
3c890 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
3c8a0 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f s an open BLOB o
3c8b0 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 n which.** [sqli
3c8c0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
3c8d0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
3c8e0 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 I/O] can be per
3c8f0 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 formed..** ^Obje
3c900 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 cts of this type
3c910 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 are created by
3c920 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
3c930 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 en()].** and des
3c940 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
3c950 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
3c960 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 ..** ^The [sqlit
3c970 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 e3_blob_read()]
3c980 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f and [sqlite3_blo
3c990 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 b_write()] inter
3c9a0 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 faces.** can be
3c9b0 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 used to read or
3c9c0 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 write small subs
3c9d0 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 ections of the B
3c9e0 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 LOB..** ^The [sq
3c9f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
3ca00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 ()] interface re
3ca10 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f turns the size o
3ca20 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 f the BLOB in by
3ca30 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 tes..*/.typedef
3ca40 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 struct sqlite3_b
3ca50 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 lob sqlite3_blob
3ca60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3ca70 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 F: Open A BLOB F
3ca80 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 or Incremental I
3ca90 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 /O.**.** ^(This
3caa0 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 interfaces opens
3cab0 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 a [BLOB handle
3cac0 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 | handle] to the
3cad0 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a BLOB located.**
3cae0 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f in row iRow, co
3caf0 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 lumn zColumn, ta
3cb00 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 ble zTable in da
3cb10 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 tabase zDb;.** i
3cb20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
3cb30 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 he same BLOB tha
3cb40 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 t would be selec
3cb50 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 ted by:.**.** <p
3cb60 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 re>.** SELEC
3cb70 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a T zColumn FROM z
3cb80 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 Db.zTable WHERE
3cb90 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a [rowid] = iRow;.
3cba0 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a ** </pre>)^.**.*
3cbb0 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 * ^If the flags
3cbc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e parameter is non
3cbd0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 -zero, then the
3cbe0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 BLOB is opened f
3cbf0 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 or read.** and w
3cc00 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 rite access. ^If
3cc10 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 it is zero, the
3cc20 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 BLOB is opened
3cc30 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e for read access.
3cc40 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 .** ^It is not p
3cc50 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 ossible to open
3cc60 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 a column that is
3cc70 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 part of an inde
3cc80 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a x or primary .**
3cc90 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 key for writing
3cca0 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b . ^If [foreign k
3ccb0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 ey constraints]
3ccc0 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 are enabled, it
3ccd0 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 is .** not possi
3cce0 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f ble to open a co
3ccf0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 lumn that is par
3cd00 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 t of a [child ke
3cd10 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a y] for writing..
3cd20 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 **.** ^Note that
3cd30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
3cd40 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 me is not the fi
3cd50 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 lename that cont
3cd60 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 ains.** the data
3cd70 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 base but rather
3cd80 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d the symbolic nam
3cd90 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
3cda0 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 e that.** appear
3cdb0 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b s after the AS k
3cdc0 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 eyword when the
3cdd0 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e database is conn
3cde0 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 ected using [ATT
3cdf0 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 ACH]..** ^For th
3ce00 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
3ce10 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 file, the databa
3ce20 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e se name is "main
3ce30 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 "..** ^For TEMP
3ce40 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 tables, the data
3ce50 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 base name is "te
3ce60 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 mp"..**.** ^(On
3ce70 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 success, [SQLITE
3ce80 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
3ce90 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c and the new [BL
3cea0 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 OB handle] is wr
3ceb0 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 itten.** to *ppB
3cec0 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 lob. Otherwise a
3ced0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
3cee0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a s returned and *
3cef0 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a ppBlob is set.**
3cf00 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f to be a null po
3cf10 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 inter.)^.** ^Thi
3cf20 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 s function sets
3cf30 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
3cf40 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 nnection] error
3cf50 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
3cf60 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 .** accessible v
3cf70 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 ia [sqlite3_errc
3cf80 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ode()] and [sqli
3cf90 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e te3_errmsg()] an
3cfa0 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e d related.** fun
3cfb0 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 ctions. ^Note th
3cfc0 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 at the *ppBlob v
3cfd0 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 ariable is alway
3cfe0 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e s initialized in
3cff0 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d a.** way that m
3d000 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 akes it safe to
3d010 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f invoke [sqlite3_
3d020 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e blob_close()] on
3d030 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 *ppBlob.** rega
3d040 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 rdless of the su
3d050 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
3d060 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
3d070 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 ..**.** ^(If the
3d080 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 row that a BLOB
3d090 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 handle points t
3d0a0 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 o is modified by
3d0b0 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c an.** [UPDATE],
3d0c0 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 [DELETE], or by
3d0d0 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 [ON CONFLICT] s
3d0e0 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 ide-effects.** t
3d0f0 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e hen the BLOB han
3d100 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 dle is marked as
3d110 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 "expired"..** T
3d120 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 his is true if a
3d130 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 ny column of the
3d140 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c row is changed,
3d150 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a even a column.*
3d160 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 * other than the
3d170 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 one the BLOB ha
3d180 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e ndle is open on.
3d190 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 )^.** ^Calls to
3d1a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
3d1b0 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ad()] and [sqlit
3d1c0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d e3_blob_write()]
3d1d0 20 66 6f 72 0a 2a 2a 20 61 6e 20 65 78 70 69 72 for.** an expir
3d1e0 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 ed BLOB handle f
3d1f0 61 69 6c 20 77 69 74 68 20 61 20 72 65 74 75 72 ail with a retur
3d200 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 n code of [SQLIT
3d210 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 E_ABORT]..** ^(C
3d220 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 hanges written i
3d230 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 nto a BLOB prior
3d240 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 to the BLOB exp
3d250 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a iring are not.**
3d260 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 rolled back by
3d270 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f the expiration o
3d280 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 f the BLOB. Suc
3d290 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 h changes will e
3d2a0 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d ventually.** com
3d2b0 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 mit if the trans
3d2c0 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 action continues
3d2d0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 to completion.)
3d2e0 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 ^.**.** ^Use the
3d2f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 [sqlite3_blob_b
3d300 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 ytes()] interfac
3d310 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 e to determine t
3d320 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 he size of.** th
3d330 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 e opened blob.
3d340 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 ^The size of a b
3d350 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 lob may not be c
3d360 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a hanged by this.*
3d370 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 * interface. Us
3d380 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 e the [UPDATE] S
3d390 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 QL command to ch
3d3a0 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 ange the size of
3d3b0 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a a.** blob..**.*
3d3c0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
3d3d0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d bind_zeroblob()]
3d3e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
3d3f0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d sult_zeroblob()]
3d400 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
3d410 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 nd the built-in
3d420 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 [zeroblob] SQL f
3d430 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 unction can be u
3d440 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c sed, if desired,
3d450 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e .** to create an
3d460 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c empty, zero-fil
3d470 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 led blob in whic
3d480 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 h to read or wri
3d490 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 te using.** this
3d4a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
3d4b0 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 * To avoid a res
3d4c0 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 ource leak, ever
3d4d0 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e y open [BLOB han
3d4e0 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e dle] should even
3d4f0 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c tually.** be rel
3d500 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 eased by a call
3d510 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 to [sqlite3_blob
3d520 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 53 51 _close()]..*/.SQ
3d530 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
3d540 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a ite3_blob_open(.
3d550 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f sqlite3*,. co
3d560 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 nst char *zDb,.
3d570 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 const char *zTa
3d580 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 ble,. const cha
3d590 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 r *zColumn,. sq
3d5a0 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 lite3_int64 iRow
3d5b0 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 ,. int flags,.
3d5c0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a sqlite3_blob **
3d5d0 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ppBlob.);../*.**
3d5e0 20 43 41 50 49 33 52 45 46 3a 20 4d 6f 76 65 20 CAPI3REF: Move
3d5f0 61 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 74 6f a BLOB Handle to
3d600 20 61 20 4e 65 77 20 52 6f 77 0a 2a 2a 0a 2a 2a a New Row.**.**
3d610 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
3d620 69 73 20 75 73 65 64 20 74 6f 20 6d 6f 76 65 20 is used to move
3d630 61 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f 62 an existing blob
3d640 20 68 61 6e 64 6c 65 20 73 6f 20 74 68 61 74 20 handle so that
3d650 69 74 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 it points.** to
3d660 61 20 64 69 66 66 65 72 65 6e 74 20 72 6f 77 20 a different row
3d670 6f 66 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 of the same data
3d680 62 61 73 65 20 74 61 62 6c 65 2e 20 5e 54 68 65 base table. ^The
3d690 20 6e 65 77 20 72 6f 77 20 69 73 20 69 64 65 6e new row is iden
3d6a0 74 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 tified.** by the
3d6b0 20 72 6f 77 69 64 20 76 61 6c 75 65 20 70 61 73 rowid value pas
3d6c0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
3d6d0 64 20 61 72 67 75 6d 65 6e 74 2e 20 4f 6e 6c 79 d argument. Only
3d6e0 20 74 68 65 20 72 6f 77 20 63 61 6e 20 62 65 0a the row can be.
3d6f0 2a 2a 20 63 68 61 6e 67 65 64 2e 20 5e 54 68 65 ** changed. ^The
3d700 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
3d710 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6f 6e 20 77 and column on w
3d720 68 69 63 68 20 74 68 65 20 62 6c 6f 62 20 68 61 hich the blob ha
3d730 6e 64 6c 65 20 69 73 20 6f 70 65 6e 0a 2a 2a 20 ndle is open.**
3d740 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65 2e remain the same.
3d750 20 4d 6f 76 69 6e 67 20 61 6e 20 65 78 69 73 74 Moving an exist
3d760 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 ing blob handle
3d770 74 6f 20 61 20 6e 65 77 20 72 6f 77 20 63 61 6e to a new row can
3d780 20 62 65 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 be.** faster th
3d790 61 6e 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 65 an closing the e
3d7a0 78 69 73 74 69 6e 67 20 68 61 6e 64 6c 65 20 61 xisting handle a
3d7b0 6e 64 20 6f 70 65 6e 69 6e 67 20 61 20 6e 65 77 nd opening a new
3d7c0 20 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 one..**.** ^(Th
3d7d0 65 20 6e 65 77 20 72 6f 77 20 6d 75 73 74 20 6d e new row must m
3d7e0 65 65 74 20 74 68 65 20 73 61 6d 65 20 63 72 69 eet the same cri
3d7f0 74 65 72 69 61 20 61 73 20 66 6f 72 20 5b 73 71 teria as for [sq
3d800 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
3d810 29 5d 20 2d 0a 2a 2a 20 69 74 20 6d 75 73 74 20 )] -.** it must
3d820 65 78 69 73 74 20 61 6e 64 20 74 68 65 72 65 20 exist and there
3d830 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 must be either a
3d840 20 62 6c 6f 62 20 6f 72 20 74 65 78 74 20 76 61 blob or text va
3d850 6c 75 65 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a lue stored in.**
3d860 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 63 the nominated c
3d870 6f 6c 75 6d 6e 2e 29 5e 20 5e 49 66 20 74 68 65 olumn.)^ ^If the
3d880 20 6e 65 77 20 72 6f 77 20 69 73 20 6e 6f 74 20 new row is not
3d890 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20 74 present in the t
3d8a0 61 62 6c 65 2c 20 6f 72 20 69 66 0a 2a 2a 20 69 able, or if.** i
3d8b0 74 20 64 6f 65 73 20 6e 6f 74 20 63 6f 6e 74 61 t does not conta
3d8c0 69 6e 20 61 20 62 6c 6f 62 20 6f 72 20 74 65 78 in a blob or tex
3d8d0 74 20 76 61 6c 75 65 2c 20 6f 72 20 69 66 20 61 t value, or if a
3d8e0 6e 6f 74 68 65 72 20 65 72 72 6f 72 20 6f 63 63 nother error occ
3d8f0 75 72 73 2c 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 urs, an.** SQLit
3d900 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 e error code is
3d910 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 returned and the
3d920 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73 20 blob handle is
3d930 63 6f 6e 73 69 64 65 72 65 64 20 61 62 6f 72 74 considered abort
3d940 65 64 2e 0a 2a 2a 20 5e 41 6c 6c 20 73 75 62 73 ed..** ^All subs
3d950 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
3d960 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
3d970 61 64 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ad()], [sqlite3_
3d980 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 6f 72 blob_write()] or
3d990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
3d9a0 62 5f 72 65 6f 70 65 6e 28 29 5d 20 6f 6e 20 61 b_reopen()] on a
3d9b0 6e 20 61 62 6f 72 74 65 64 20 62 6c 6f 62 20 68 n aborted blob h
3d9c0 61 6e 64 6c 65 20 69 6d 6d 65 64 69 61 74 65 6c andle immediatel
3d9d0 79 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 y return.** SQLI
3d9e0 54 45 5f 41 42 4f 52 54 2e 20 5e 43 61 6c 6c 69 TE_ABORT. ^Calli
3d9f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ng [sqlite3_blob
3da00 5f 62 79 74 65 73 28 29 5d 20 6f 6e 20 61 6e 20 _bytes()] on an
3da10 61 62 6f 72 74 65 64 20 62 6c 6f 62 20 68 61 6e aborted blob han
3da20 64 6c 65 0a 2a 2a 20 61 6c 77 61 79 73 20 72 65 dle.** always re
3da30 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
3da40 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
3da50 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61 sets the databa
3da60 73 65 20 68 61 6e 64 6c 65 20 65 72 72 6f 72 20 se handle error
3da70 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
3da80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
3da90 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
3daa0 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
3dab0 62 6c 6f 62 5f 72 65 6f 70 65 6e 28 73 71 6c 69 blob_reopen(sqli
3dac0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 73 71 6c 69 te3_blob *, sqli
3dad0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a te3_int64);../*.
3dae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f ** CAPI3REF: Clo
3daf0 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 se A BLOB Handle
3db00 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 .**.** ^Closes a
3db10 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e n open [BLOB han
3db20 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f dle]..**.** ^Clo
3db30 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c sing a BLOB shal
3db40 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 l cause the curr
3db50 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ent transaction
3db60 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 to commit.** if
3db70 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 there are no oth
3db80 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e er BLOBs, no pen
3db90 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 ding prepared st
3dba0 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 atements, and th
3dbb0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
3dbc0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b nnection is in [
3dbd0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d autocommit mode]
3dbe0 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69 ..** ^If any wri
3dbf0 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f tes were made to
3dc00 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 the BLOB, they
3dc10 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e might be held in
3dc20 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 cache.** until
3dc30 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 the close operat
3dc40 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c ion if they will
3dc50 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c fit..**.** ^(Cl
3dc60 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f osing the BLOB o
3dc70 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 ften forces the
3dc80 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 changes.** out t
3dc90 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 o disk and so if
3dca0 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 any I/O errors
3dcb0 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c occur, they will
3dcc0 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a likely occur.**
3dcd0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 at the time whe
3dce0 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c n the BLOB is cl
3dcf0 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 osed. Any error
3dd00 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 s that occur dur
3dd10 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 ing.** closing a
3dd20 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 re reported as a
3dd30 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e non-zero return
3dd40 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 value.)^.**.**
3dd50 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c ^(The BLOB is cl
3dd60 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e osed uncondition
3dd70 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 ally. Even if t
3dd80 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
3dd90 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 rns.** an error
3dda0 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 code, the BLOB i
3ddb0 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 s still closed.)
3ddc0 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ^.**.** ^Calling
3ddd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
3dde0 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 th a null pointe
3ddf0 72 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64 r (such as would
3de00 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 be returned.**
3de10 62 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c by a failed call
3de20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
3de30 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20 b_open()]) is a
3de40 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
3de50 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
3de60 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 t sqlite3_blob_c
3de70 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f lose(sqlite3_blo
3de80 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 b *);../*.** CAP
3de90 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 I3REF: Return Th
3dea0 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 e Size Of An Ope
3deb0 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 n BLOB.**.** ^Re
3dec0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 turns the size i
3ded0 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 n bytes of the B
3dee0 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 LOB accessible v
3def0 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 ia the .** succe
3df00 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b ssfully opened [
3df10 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 BLOB handle] in
3df20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e its only argumen
3df30 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 t. ^The.** incr
3df40 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f emental blob I/O
3df50 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e routines can on
3df60 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 ly read or overw
3df70 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a riting existing.
3df80 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b ** blob content;
3df90 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 they cannot cha
3dfa0 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 nge the size of
3dfb0 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 a blob..**.** Th
3dfc0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 is routine only
3dfd0 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 works on a [BLOB
3dfe0 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 handle] which h
3dff0 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a as been created.
3e000 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 ** by a prior su
3e010 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
3e020 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
3e030 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 pen()] and which
3e040 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e has not.** been
3e050 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 closed by [sqli
3e060 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
3e070 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 ]. Passing any
3e080 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e other pointer in
3e090 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 .** to this rout
3e0a0 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ine results in u
3e0b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
3e0c0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
3e0d0 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 53 e behavior..*/.S
3e0e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
3e0f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
3e100 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 (sqlite3_blob *)
3e110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3e120 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f F: Read Data Fro
3e130 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 m A BLOB Increme
3e140 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 ntally.**.** ^(T
3e150 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
3e160 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 used to read dat
3e170 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b a from an open [
3e180 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 BLOB handle] int
3e190 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 o a.** caller-su
3e1a0 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e pplied buffer. N
3e1b0 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 bytes of data a
3e1c0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 re copied into b
3e1d0 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 uffer Z.** from
3e1e0 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 the open BLOB, s
3e1f0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 tarting at offse
3e200 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a t iOffset.)^.**.
3e210 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f ** ^If offset iO
3e220 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 ffset is less th
3e230 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 an N bytes from
3e240 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 the end of the B
3e250 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f LOB,.** [SQLITE_
3e260 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e ERROR] is return
3e270 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 ed and no data i
3e280 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f s read. ^If N o
3e290 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 r iOffset is.**
3e2a0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 less than zero,
3e2b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
3e2c0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
3e2d0 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a o data is read..
3e2e0 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 ** ^The size of
3e2f0 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 the blob (and he
3e300 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 nce the maximum
3e310 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 value of N+iOffs
3e320 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 et).** can be de
3e330 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 termined using t
3e340 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
3e350 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
3e360 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 ace..**.** ^An a
3e370 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 ttempt to read f
3e380 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b rom an expired [
3e390 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 BLOB handle] fai
3e3a0 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 ls with an.** er
3e3b0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
3e3c0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
3e3d0 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 * ^(On success,
3e3e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 sqlite3_blob_rea
3e3f0 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 d() returns SQLI
3e400 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 TE_OK..** Otherw
3e410 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 ise, an [error c
3e420 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 ode] or an [exte
3e430 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
3e440 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a is returned.)^.
3e450 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
3e460 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e ne only works on
3e470 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d a [BLOB handle]
3e480 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 which has been
3e490 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 created.** by a
3e4a0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c prior successful
3e4b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
3e4c0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 3_blob_open()] a
3e4d0 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 nd which has not
3e4e0 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 .** been closed
3e4f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 by [sqlite3_blob
3e500 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 _close()]. Pass
3e510 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f ing any other po
3e520 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 inter in.** to t
3e530 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 his routine resu
3e540 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
3e550 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e and probably un
3e560 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 desirable behavi
3e570 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c or..**.** See al
3e580 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f so: [sqlite3_blo
3e590 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 53 b_write()]..*/.S
3e5a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
3e5b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
3e5c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 sqlite3_blob *,
3e5d0 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 void *Z, int N,
3e5e0 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f int iOffset);../
3e5f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 *.** CAPI3REF: W
3e600 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 rite Data Into A
3e610 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 BLOB Incrementa
3e620 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 lly.**.** ^This
3e630 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 function is used
3e640 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 to write data i
3e650 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f nto an open [BLO
3e660 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 B handle] from a
3e670 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c .** caller-suppl
3e680 69 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 ied buffer. ^N b
3e690 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 ytes of data are
3e6a0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 copied from the
3e6b0 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 buffer Z.** int
3e6c0 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c o the open BLOB,
3e6d0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 starting at off
3e6e0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a set iOffset..**.
3e6f0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 ** ^If the [BLOB
3e700 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 handle] passed
3e710 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
3e720 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 ument was not op
3e730 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 ened for.** writ
3e740 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 ing (the flags p
3e750 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
3e760 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
3e770 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 ] was zero),.**
3e780 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 this function re
3e790 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 turns [SQLITE_RE
3e7a0 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e ADONLY]..**.** ^
3e7b0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 This function ma
3e7c0 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 y only modify th
3e7d0 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 e contents of th
3e7e0 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a e BLOB; it is.**
3e7f0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
3e800 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 increase the si
3e810 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 ze of a BLOB usi
3e820 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 ng this API..**
3e830 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 ^If offset iOffs
3e840 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 et is less than
3e850 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 N bytes from the
3e860 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 end of the BLOB
3e870 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 ,.** [SQLITE_ERR
3e880 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OR] is returned
3e890 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 and no data is w
3e8a0 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69 ritten. ^If N i
3e8b0 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a s.** less than z
3e8c0 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ero [SQLITE_ERRO
3e8d0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
3e8e0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 nd no data is wr
3e8f0 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 itten..** The si
3e900 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 ze of the BLOB (
3e910 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 and hence the ma
3e920 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e ximum value of N
3e930 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e +iOffset).** can
3e940 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
3e950 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
3e960 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 3_blob_bytes()]
3e970 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
3e980 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 ^An attempt to
3e990 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 write to an expi
3e9a0 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 red [BLOB handle
3e9b0 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a ] fails with an.
3e9c0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 ** error code of
3e9d0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e [SQLITE_ABORT].
3e9e0 20 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65 ^Writes to the
3e9f0 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 BLOB that occur
3ea00 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 red.** before th
3ea10 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 e [BLOB handle]
3ea20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 expired are not
3ea30 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 rolled back by t
3ea40 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e he.** expiration
3ea50 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 of the handle,
3ea60 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 though of course
3ea70 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d those changes m
3ea80 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 ight.** have bee
3ea90 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 n overwritten by
3eaa0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
3eab0 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65 20 hat expired the
3eac0 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f BLOB handle.** o
3ead0 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 r by other indep
3eae0 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 endent statement
3eaf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 s..**.** ^(On su
3eb00 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 ccess, sqlite3_b
3eb10 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74 75 lob_write() retu
3eb20 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a rns SQLITE_OK..*
3eb30 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 * Otherwise, an
3eb40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 [error code] or
3eb50 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 an [extended er
3eb60 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
3eb70 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 urned.)^.**.** T
3eb80 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 his routine only
3eb90 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f works on a [BLO
3eba0 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 B handle] which
3ebb0 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 has been created
3ebc0 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 .** by a prior s
3ebd0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
3ebe0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f o [sqlite3_blob_
3ebf0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 open()] and whic
3ec00 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 h has not.** bee
3ec10 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c n closed by [sql
3ec20 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
3ec30 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 )]. Passing any
3ec40 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 other pointer i
3ec50 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 n.** to this rou
3ec60 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 tine results in
3ec70 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
3ec80 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 obably undesirab
3ec90 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a le behavior..**.
3eca0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
3ecb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
3ecc0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
3ecd0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c I int sqlite3_bl
3ece0 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 ob_write(sqlite3
3ecf0 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 _blob *, const v
3ed00 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 oid *z, int n, i
3ed10 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a nt iOffset);../*
3ed20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
3ed30 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 rtual File Syste
3ed40 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 m Objects.**.**
3ed50 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 A virtual filesy
3ed60 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e stem (VFS) is an
3ed70 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
3ed80 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 bject.** that SQ
3ed90 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 Lite uses to int
3eda0 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 eract.** with th
3edb0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
3edc0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
3edd0 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c Most SQLite buil
3ede0 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a ds come with a.*
3edf0 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 * single default
3ee00 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 VFS that is app
3ee10 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 ropriate for the
3ee20 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a host computer..
3ee30 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e ** New VFSes can
3ee40 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 be registered a
3ee50 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 nd existing VFSe
3ee60 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 s can be unregis
3ee70 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f tered..** The fo
3ee80 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 llowing interfac
3ee90 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e es are provided.
3eea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
3eeb0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 te3_vfs_find() i
3eec0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
3eed0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
3eee0 56 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 VFS given its na
3eef0 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 me..** ^Names ar
3ef00 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 e case sensitive
3ef10 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 ..** ^Names are
3ef20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
3ef30 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a UTF-8 strings..*
3ef40 2a 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e * ^If there is n
3ef50 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 o match, a NULL
3ef60 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
3ef70 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 ned..** ^If zVfs
3ef80 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 Name is NULL the
3ef90 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 n the default VF
3efa0 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a S is returned..*
3efb0 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20 *.** ^New VFSes
3efc0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 are registered w
3efd0 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f ith sqlite3_vfs_
3efe0 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e register()..** ^
3eff0 45 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 Each new VFS bec
3f000 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 omes the default
3f010 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 VFS if the make
3f020 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 Dflt flag is set
3f030 2e 0a 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56 ..** ^The same V
3f040 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 FS can be regist
3f050 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 ered multiple ti
3f060 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 mes without inju
3f070 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 ry..** ^To make
3f080 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 an existing VFS
3f090 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 into the default
3f0a0 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 VFS, register i
3f0b0 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 t again.** with
3f0c0 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 the makeDflt fla
3f0d0 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 g set. If two d
3f0e0 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 ifferent VFSes w
3f0f0 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 ith the.** same
3f100 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 name are registe
3f110 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f red, the behavio
3f120 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 r is undefined.
3f130 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 If a.** VFS is
3f140 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 registered with
3f150 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e a name that is N
3f160 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 ULL or an empty
3f170 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 string,.** then
3f180 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
3f190 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
3f1a0 20 5e 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 ^Unregister a V
3f1b0 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 FS with the sqli
3f1c0 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 te3_vfs_unregist
3f1d0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a er() interface..
3f1e0 2a 2a 20 5e 28 49 66 20 74 68 65 20 64 65 66 61 ** ^(If the defa
3f1f0 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 ult VFS is unreg
3f200 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 istered, another
3f210 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 VFS is chosen a
3f220 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 s.** the default
3f230 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f . The choice fo
3f240 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 r the new VFS is
3f250 20 61 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f arbitrary.)^.*/
3f260 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
3f270 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 te3_vfs *sqlite3
3f280 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 _vfs_find(const
3f290 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b char *zVfsName);
3f2a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
3f2b0 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
3f2c0 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 ster(sqlite3_vfs
3f2d0 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 *, int makeDflt)
3f2e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
3f2f0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 sqlite3_vfs_unr
3f300 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f egister(sqlite3_
3f310 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 vfs*);../*.** CA
3f320 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a PI3REF: Mutexes.
3f330 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 **.** The SQLite
3f340 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 core uses these
3f350 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 routines for th
3f360 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e read.** synchron
3f370 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 ization. Though
3f380 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 they are intende
3f390 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a d for internal.*
3f3a0 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c * use by SQLite,
3f3b0 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 code that links
3f3c0 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 against SQLite
3f3d0 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 is.** permitted
3f3e0 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 to use any of th
3f3f0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ese routines..**
3f400 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 .** The SQLite s
3f410 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 ource code conta
3f420 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ins multiple imp
3f430 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 lementations.**
3f440 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 of these mutex r
3f450 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 outines. An app
3f460 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 ropriate impleme
3f470 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 ntation.** is se
3f480 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 lected automatic
3f490 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d ally at compile-
3f4a0 74 69 6d 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c time. ^(The fol
3f4b0 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d lowing.** implem
3f4c0 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 entations are av
3f4d0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 ailable in the S
3f4e0 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a QLite core:.**.*
3f4f0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
3f500 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 SQLITE_MUTEX_OS
3f510 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 2.** <li> SQLI
3f520 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 TE_MUTEX_PTHREAD
3f530 53 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 S.** <li> SQLI
3f540 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 TE_MUTEX_W32.**
3f550 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
3f560 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c TEX_NOOP.** </ul
3f570 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 >)^.**.** ^The S
3f580 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 QLITE_MUTEX_NOOP
3f590 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
3f5a0 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 is a set of rout
3f5b0 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 ines.** that doe
3f5c0 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e s no real lockin
3f5d0 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 g and is appropr
3f5e0 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e 0a iate for use in.
3f5f0 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 ** a single-thre
3f600 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e aded application
3f610 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d . ^The SQLITE_M
3f620 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c UTEX_OS2,.** SQL
3f630 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 ITE_MUTEX_PTHREA
3f640 44 53 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d DS, and SQLITE_M
3f650 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 UTEX_W32 impleme
3f660 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 ntations.** are
3f670 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
3f680 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 use on OS/2, Uni
3f690 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a x, and Windows..
3f6a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 **.** ^(If SQLit
3f6b0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
3f6c0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 th the SQLITE_MU
3f6d0 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 TEX_APPDEF prepr
3f6e0 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f ocessor.** macro
3f6f0 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 defined (with "
3f700 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 -DSQLITE_MUTEX_A
3f710 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 PPDEF=1"), then
3f720 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c no mutex.** impl
3f730 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e ementation is in
3f740 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 cluded with the
3f750 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73 library. In this
3f760 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 case the.** app
3f770 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 lication must su
3f780 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 pply a custom mu
3f790 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
3f7a0 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 on using the.**
3f7b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
3f7c0 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 UTEX] option of
3f7d0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 the sqlite3_conf
3f7e0 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a ig() function.**
3f7f0 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 before calling
3f800 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
3f810 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 ze() or any othe
3f820 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 r public sqlite3
3f830 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 _.** function th
3f840 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 at calls sqlite3
3f850 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 29 5e _initialize().)^
3f860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
3f870 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
3f880 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 ) routine alloca
3f890 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 tes a new.** mut
3f8a0 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 ex and returns a
3f8b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 pointer to it.
3f8c0 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e ^If it returns N
3f8d0 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e ULL.** that mean
3f8e0 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 s that a mutex c
3f8f0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f ould not be allo
3f900 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74 65 0a cated. ^SQLite.
3f910 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 ** will unwind i
3f920 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 ts stack and ret
3f930 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e urn an error. ^
3f940 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a (The argument.**
3f950 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
3f960 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 x_alloc() is one
3f970 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
3f980 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a r constants:.**.
3f990 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
3f9a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
3f9b0 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ST.** <li> SQLI
3f9c0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
3f9d0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 VE.** <li> SQLI
3f9e0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
3f9f0 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 MASTER.** <li>
3fa00 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
3fa10 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 TIC_MEM.** <li>
3fa20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
3fa30 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 ATIC_MEM2.** <li
3fa40 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
3fa50 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c STATIC_PRNG.** <
3fa60 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
3fa70 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 X_STATIC_LRU.**
3fa80 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
3fa90 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a EX_STATIC_LRU2.*
3faa0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
3fab0 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 ^The first two c
3fac0 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49 54 45 onstants (SQLITE
3fad0 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 _MUTEX_FAST and
3fae0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
3faf0 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75 73 65 URSIVE).** cause
3fb00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
3fb10 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 lloc() to create
3fb20 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e .** a new mutex.
3fb30 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74 65 78 ^The new mutex
3fb40 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 is recursive wh
3fb50 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f en SQLITE_MUTEX_
3fb60 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 RECURSIVE.** is
3fb70 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 used but not nec
3fb80 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e essarily so when
3fb90 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
3fba0 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 ST is used..** T
3fbb0 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 he mutex impleme
3fbc0 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ntation does not
3fbd0 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 need to make a
3fbe0 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
3fbf0 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 etween SQLITE_MU
3fc00 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e TEX_RECURSIVE an
3fc10 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 d SQLITE_MUTEX_F
3fc20 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a AST if it does.*
3fc30 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 * not want to.
3fc40 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c ^SQLite will onl
3fc50 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 y request a recu
3fc60 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a rsive mutex in.*
3fc70 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 * cases where it
3fc80 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e really needs on
3fc90 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74 65 72 e. ^If a faster
3fca0 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d non-recursive m
3fcb0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
3fcc0 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 tation is availa
3fcd0 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 ble on the host
3fce0 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 platform, the mu
3fcf0 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a tex subsystem.**
3fd00 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 might return su
3fd10 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 ch a mutex in re
3fd20 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 sponse to SQLITE
3fd30 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a _MUTEX_FAST..**.
3fd40 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20 61 6c ** ^The other al
3fd50 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 lowed parameters
3fd60 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
3fd70 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79 74 68 x_alloc() (anyth
3fd80 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74 68 61 ing other.** tha
3fd90 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 n SQLITE_MUTEX_F
3fda0 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d AST and SQLITE_M
3fdb0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 UTEX_RECURSIVE)
3fdc0 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 each return.** a
3fdd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 pointer to a st
3fde0 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 atic preexisting
3fdf0 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20 73 74 mutex. ^Six st
3fe00 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 atic mutexes are
3fe10 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 .** used by the
3fe20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 current version
3fe30 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 of SQLite. Futu
3fe40 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
3fe50 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 QLite.** may add
3fe60 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 additional stat
3fe70 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 ic mutexes. Sta
3fe80 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 tic mutexes are
3fe90 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 for internal.**
3fea0 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e use by SQLite on
3feb0 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ly. Application
3fec0 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 s that use SQLit
3fed0 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 e mutexes should
3fee0 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 .** use only the
3fef0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 dynamic mutexes
3ff00 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c returned by SQL
3ff10 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f ITE_MUTEX_FAST o
3ff20 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 r.** SQLITE_MUTE
3ff30 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a X_RECURSIVE..**.
3ff40 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 69 66 ** ^Note that if
3ff50 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 one of the dyna
3ff60 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 mic mutex parame
3ff70 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 ters (SQLITE_MUT
3ff80 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 EX_FAST.** or SQ
3ff90 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
3ffa0 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68 SIVE) is used th
3ffb0 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 en sqlite3_mutex
3ffc0 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 _alloc().** retu
3ffd0 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 rns a different
3ffe0 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 mutex on every c
3fff0 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72 20 74 all. ^But for t
40000 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 he static.** mut
40010 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 ex types, the sa
40020 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 me mutex is retu
40030 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 rned on every ca
40040 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 ll that has.** t
40050 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d he same type num
40060 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
40070 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
40080 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 ee() routine dea
40090 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 llocates a previ
400a0 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ously.** allocat
400b0 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ed dynamic mutex
400c0 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20 63 61 . ^SQLite is ca
400d0 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 reful to dealloc
400e0 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e ate every.** dyn
400f0 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 amic mutex that
40100 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 it allocates. T
40110 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
40120 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 es must not be i
40130 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 n.** use when th
40140 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 ey are deallocat
40150 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20 ed. Attempting
40160 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 to deallocate a
40170 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 static.** mutex
40180 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 results in undef
40190 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20 ined behavior.
401a0 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 ^SQLite never de
401b0 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 allocates.** a s
401c0 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a tatic mutex..**.
401d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
401e0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e mutex_enter() an
401f0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
40200 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 try() routines a
40210 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 ttempt.** to ent
40220 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e 49 66 er a mutex. ^If
40230 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
40240 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 is already withi
40250 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 n the mutex,.**
40260 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
40270 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b ter() will block
40280 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
40290 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 ex_try() will re
402a0 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 turn.** SQLITE_B
402b0 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 USY. ^The sqlit
402c0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 e3_mutex_try() i
402d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
402e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 [SQLITE_OK].**
402f0 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 upon successful
40300 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65 78 65 entry. ^(Mutexe
40310 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a s created using.
40320 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ** SQLITE_MUTEX_
40330 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 RECURSIVE can be
40340 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c entered multipl
40350 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 e times by the s
40360 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 ame thread..** I
40370 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68 65 n such cases the
40380 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 ,.** mutex must
40390 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 75 be exited an equ
403a0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d al number of tim
403b0 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 es before anothe
403c0 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 r thread.** can
403d0 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66 20 74 enter.)^ ^(If t
403e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 he same thread t
403f0 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e ries to enter an
40400 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 y other.** kind
40410 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 of mutex more th
40420 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 an once, the beh
40430 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
40440 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 ed..** SQLite wi
40450 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 ll never exhibit
40460 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f .** such behavio
40470 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 r in its own use
40480 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a of mutexes.)^.*
40490 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79 73 74 *.** ^(Some syst
404a0 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ems (for example
404b0 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f , Windows 95) do
404c0 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 not support the
404d0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d operation.** im
404e0 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c plemented by sql
404f0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
40500 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 . On those syst
40510 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 ems, sqlite3_mut
40520 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c ex_try().** will
40530 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 always return S
40540 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68 65 QLITE_BUSY. The
40550 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c SQLite core onl
40560 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 y ever uses.** s
40570 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
40580 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a () as an optimiz
40590 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 ation so this is
405a0 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 acceptable beha
405b0 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 vior.)^.**.** ^T
405c0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
405d0 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 _leave() routine
405e0 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 exits a mutex t
405f0 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 hat was.** previ
40600 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 ously entered by
40610 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
40620 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61 76 69 . ^(The behavi
40630 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e or.** is undefin
40640 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 ed if the mutex
40650 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
40660 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a entered by the.
40670 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 ** calling threa
40680 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72 d or is not curr
40690 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e ently allocated.
406a0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a SQLite will.**
406b0 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 never do either
406c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 .)^.**.** ^If th
406d0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 e argument to sq
406e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
406f0 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 r(), sqlite3_mut
40700 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 ex_try(), or.**
40710 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
40720 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 ave() is a NULL
40730 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c pointer, then al
40740 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 l three routines
40750 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f .** behave as no
40760 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 -ops..**.** See
40770 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d also: [sqlite3_m
40780 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 utex_held()] and
40790 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
407a0 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 53 notheld()]..*/.S
407b0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
407c0 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 3_mutex *sqlite3
407d0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 _mutex_alloc(int
407e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
407f0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 id sqlite3_mutex
40800 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 _free(sqlite3_mu
40810 74 65 78 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 tex*);.SQLITE_AP
40820 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d I void sqlite3_m
40830 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 utex_enter(sqlit
40840 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 e3_mutex*);.SQLI
40850 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
40860 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c e3_mutex_try(sql
40870 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 51 ite3_mutex*);.SQ
40880 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
40890 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
408a0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a e(sqlite3_mutex*
408b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
408c0 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 EF: Mutex Method
408d0 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 s Object.**.** A
408e0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
408f0 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 is structure def
40900 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 ines the low-lev
40910 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 el routines.** u
40920 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 sed to allocate
40930 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e and use mutexes.
40940 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 .**.** Usually,
40950 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
40960 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
40970 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 s provided by SQ
40980 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 Lite are.** suff
40990 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 icient, however
409a0 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 the user has the
409b0 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 option of subst
409c0 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d ituting a custom
409d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
409e0 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a on for specializ
409f0 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f ed deployments o
40a00 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 r systems for wh
40a10 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f ich SQLite.** do
40a20 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 es not provide a
40a30 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
40a40 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 entation. In thi
40a50 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 s case, the user
40a60 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 .** creates and
40a70 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 populates an ins
40a80 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 tance of this st
40a90 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a ructure to pass.
40aa0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
40ab0 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 nfig() along wit
40ac0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f h the [SQLITE_CO
40ad0 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 NFIG_MUTEX] opti
40ae0 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 on..** Additiona
40af0 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 lly, an instance
40b00 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
40b10 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 re can be used a
40b20 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 s an.** output v
40b30 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 ariable when que
40b40 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d rying the system
40b50 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
40b60 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d mutex.** implem
40b70 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 entation, using
40b80 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
40b90 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 IG_GETMUTEX] opt
40ba0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
40bb0 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f xMutexInit metho
40bc0 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 d defined by thi
40bd0 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 s structure is i
40be0 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 nvoked as.** par
40bf0 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 t of system init
40c00 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 ialization by th
40c10 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
40c20 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e lize() function.
40c30 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 .** ^The xMutexI
40c40 6e 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 nit routine is c
40c50 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 alled by SQLite
40c60 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 exactly once for
40c70 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 each.** effecti
40c80 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ve call to [sqli
40c90 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
40ca0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d ]..**.** ^The xM
40cb0 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 utexEnd method d
40cc0 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 efined by this s
40cd0 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f tructure is invo
40ce0 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f ked as.** part o
40cf0 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 f system shutdow
40d00 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 n by the sqlite3
40d10 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 _shutdown() func
40d20 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 tion. The.** imp
40d30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
40d40 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 his method is ex
40d50 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 pected to releas
40d60 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e e all outstandin
40d70 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f g.** resources o
40d80 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d btained by the m
40d90 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 utex methods imp
40da0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 lementation, esp
40db0 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 ecially.** those
40dc0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 obtained by the
40dd0 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 xMutexInit meth
40de0 6f 64 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 od. ^The xMutex
40df0 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 End().** interfa
40e00 63 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 ce is invoked ex
40e10 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 actly once for e
40e20 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ach call to [sql
40e30 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
40e40 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 ..**.** ^(The re
40e50 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 maining seven me
40e60 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 thods defined by
40e70 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 this structure
40e80 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a (xMutexAlloc,.**
40e90 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 xMutexFree, xMu
40ea0 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 texEnter, xMutex
40eb0 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 Try, xMutexLeave
40ec0 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 , xMutexHeld and
40ed0 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c .** xMutexNothel
40ee0 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 d) implement the
40ef0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 following inter
40f00 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76 faces (respectiv
40f10 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ely):.**.** <ul>
40f20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
40f30 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
40f40 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
40f50 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
40f60 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 tex_free()] </li
40f70 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
40f80 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
40f90 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 r()] </li>.**
40fa0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
40fb0 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 utex_try()] </li
40fc0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
40fd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
40fe0 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 e()] </li>.**
40ff0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
41000 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c utex_held()] </l
41010 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
41020 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
41030 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a held()] </li>.**
41040 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
41050 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e he only differen
41060 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70 ce is that the p
41070 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 ublic sqlite3_XX
41080 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d X functions enum
41090 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 erated.** above
410a0 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 silently ignore
410b0 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 any invocations
410c0 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c that pass a NULL
410d0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 pointer instead
410e0 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d .** of a valid m
410f0 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 utex handle. The
41100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
41110 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 of the methods
41120 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 defined.** by th
41130 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65 is structure are
41140 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f not required to
41150 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 handle this cas
41160 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a e, the results.*
41170 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e * of passing a N
41180 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 ULL pointer inst
41190 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d ead of a valid m
411a0 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 utex handle are
411b0 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e undefined.** (i.
411c0 65 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61 e. it is accepta
411d0 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 ble to provide a
411e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
411f0 20 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 that segfaults
41200 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 if.** it is pass
41210 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ed a NULL pointe
41220 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d r)..**.** The xM
41230 75 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f utexInit() metho
41240 64 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 d must be thread
41250 73 61 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 safe. ^It must
41260 62 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a be harmless to.*
41270 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 * invoke xMutexI
41280 6e 69 74 28 29 20 6d 75 6c 74 69 70 6c 65 20 74 nit() multiple t
41290 69 6d 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 imes within the
412a0 73 61 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 same process and
412b0 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 without.** inte
412c0 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f rvening calls to
412d0 20 78 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 xMutexEnd(). S
412e0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
412f0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a uent calls to.**
41300 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 xMutexInit() mu
41310 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a st be no-ops..**
41320 0a 2a 2a 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 .** ^xMutexInit(
41330 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 ) must not use S
41340 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c QLite memory all
41350 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 ocation ([sqlite
41360 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 3_malloc()].** a
41370 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 nd its associate
41380 73 29 2e 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c s). ^Similarly,
41390 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d xMutexAlloc() m
413a0 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 ust not use SQLi
413b0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c te memory.** all
413c0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 ocation for a st
413d0 61 74 69 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f atic mutex. ^Ho
413e0 77 65 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f wever xMutexAllo
413f0 63 28 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69 c() may use SQLi
41400 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c te.** memory all
41410 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 ocation for a fa
41420 73 74 20 6f 72 20 72 65 63 75 72 73 69 76 65 20 st or recursive
41430 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 mutex..**.** ^SQ
41440 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
41450 20 74 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 the xMutexEnd()
41460 20 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 method when [sq
41470 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
41480 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 ] is.** called,
41490 62 75 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 but only if the
414a0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d prior call to xM
414b0 75 74 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 utexInit returne
414c0 64 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 d SQLITE_OK..**
414d0 49 66 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 If xMutexInit fa
414e0 69 6c 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 ils in any way,
414f0 69 74 20 69 73 20 65 78 70 65 63 74 65 64 20 74 it is expected t
41500 6f 20 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 o clean up after
41510 20 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 itself.** prior
41520 20 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a to returning..*
41530 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
41540 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
41550 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d ethods sqlite3_m
41560 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 utex_methods;.st
41570 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 ruct sqlite3_mut
41580 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 ex_methods {. i
41590 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 nt (*xMutexInit)
415a0 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a (void);. int (*
415b0 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 xMutexEnd)(void)
415c0 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 ;. sqlite3_mute
415d0 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 x *(*xMutexAlloc
415e0 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 )(int);. void (
415f0 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c *xMutexFree)(sql
41600 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 ite3_mutex *);.
41610 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e void (*xMutexEn
41620 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 ter)(sqlite3_mut
41630 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ex *);. int (*x
41640 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 MutexTry)(sqlite
41650 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 3_mutex *);. vo
41660 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 id (*xMutexLeave
41670 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 )(sqlite3_mutex
41680 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 *);. int (*xMut
41690 65 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f exHeld)(sqlite3_
416a0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 mutex *);. int
416b0 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 (*xMutexNotheld)
416c0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
416d0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 );.};../*.** CAP
416e0 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 I3REF: Mutex Ver
416f0 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e ification Routin
41700 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c es.**.** The sql
41710 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
41720 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 ) and sqlite3_mu
41730 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f tex_notheld() ro
41740 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e utines.** are in
41750 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
41760 6e 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73 nside assert() s
41770 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 tatements. ^The
41780 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 SQLite core.**
41790 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65 never uses these
417a0 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 routines except
417b0 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 inside an asser
417c0 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 t() and applicat
417d0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 ions.** are advi
417e0 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 sed to follow th
417f0 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f e lead of the co
41800 72 65 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 re. ^The SQLite
41810 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 core only.** pr
41820 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 ovides implement
41830 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 ations for these
41840 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 routines when i
41850 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a t is compiled.**
41860 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
41870 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 _DEBUG flag. ^E
41880 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d xternal mutex im
41890 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a plementations.**
418a0 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 are only requir
418b0 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 ed to provide th
418c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 ese routines if
418d0 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a SQLITE_DEBUG is.
418e0 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 ** defined and i
418f0 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 f NDEBUG is not
41900 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
41910 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 These routines s
41920 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 hould return tru
41930 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 e if the mutex i
41940 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 n their argument
41950 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e .** is held or n
41960 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 ot held, respect
41970 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 ively, by the ca
41980 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a lling thread..**
41990 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 .** ^The impleme
419a0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 ntation is not r
419b0 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 equired to provi
419c0 64 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 de versions of t
419d0 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 hese.** routines
419e0 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 that actually w
419f0 6f 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c ork. If the impl
41a00 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 ementation does
41a10 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b not provide work
41a20 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ing.** versions
41a30 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
41a40 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 s, it should at
41a50 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 least provide st
41a60 75 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a ubs that always.
41a70 2a 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 ** return true s
41a80 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 o that one does
41a90 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 not get spurious
41aa0 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 assertion failu
41ab0 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 res..**.** ^If t
41ac0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 he argument to s
41ad0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
41ae0 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f d() is a NULL po
41af0 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 inter then.** th
41b00 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 e routine should
41b10 20 72 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 return 1. Thi
41b20 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d s seems counter-
41b30 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a intuitive since.
41b40 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d ** clearly the m
41b50 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 utex cannot be h
41b60 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e eld if it does n
41b70 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 0a 2a ot exist. But.*
41b80 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 * the reason the
41b90 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 mutex does not
41ba0 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 exist is because
41bb0 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f the build is no
41bc0 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 t.** using mutex
41bd0 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e es. And we do n
41be0 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 ot want the asse
41bf0 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 rt() containing
41c00 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 the.** call to s
41c10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
41c20 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 d() to fail, so
41c30 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 a non-zero retur
41c40 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 n is.** the appr
41c50 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f opriate thing to
41c60 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 do. ^The sqlit
41c70 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 e3_mutex_notheld
41c80 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
41c90 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 should also retu
41ca0 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 rn 1 when given
41cb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
41cc0 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55 */.#ifndef NDEBU
41cd0 47 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 G.SQLITE_API int
41ce0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
41cf0 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 eld(sqlite3_mute
41d00 78 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 x*);.SQLITE_API
41d10 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 int sqlite3_mute
41d20 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 x_notheld(sqlite
41d30 33 5f 6d 75 74 65 78 2a 29 3b 0a 23 65 6e 64 69 3_mutex*);.#endi
41d40 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
41d50 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 0a 2a F: Mutex Types.*
41d60 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
41d70 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
41d80 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 interface takes
41d90 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
41da0 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f nt.** which is o
41db0 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
41dc0 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a ger constants..*
41dd0 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f 66 20 *.** The set of
41de0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 6d static mutexes m
41df0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f ay change from o
41e00 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65 61 73 ne SQLite releas
41e10 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 e to the.** next
41e20 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
41e30 74 68 61 74 20 6f 76 65 72 72 69 64 65 20 74 68 that override th
41e40 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 e built-in mutex
41e50 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 0a 2a logic must be.*
41e60 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20 61 63 * prepared to ac
41e70 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 74 69 commodate additi
41e80 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 onal static mute
41e90 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 xes..*/.#define
41ea0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
41eb0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a T 0.
41ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
41ed0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 UTEX_RECURSIVE
41ee0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
41ef0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
41f00 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a TIC_MASTER 2.
41f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
41f20 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 UTEX_STATIC_MEM
41f30 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 3 /* sqli
41f40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a te3_malloc() */.
41f50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
41f60 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 UTEX_STATIC_MEM2
41f70 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 4 /* NOT
41f80 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 USED */.#define
41f90 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
41fa0 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 TIC_OPEN 4
41fb0 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72 65 65 /* sqlite3Btree
41fc0 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e Open() */.#defin
41fd0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
41fe0 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 TATIC_PRNG
41ff0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 5 /* sqlite3_ra
42000 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e ndom() */.#defin
42010 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
42020 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 TATIC_LRU
42030 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 6 /* lru page l
42040 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ist */.#define S
42050 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
42060 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37 20 20 IC_LRU2 7
42070 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 /* NOT USED */.#
42080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
42090 54 45 58 5f 53 54 41 54 49 43 5f 50 4d 45 4d 20 TEX_STATIC_PMEM
420a0 20 20 20 20 20 37 20 20 2f 2a 20 73 71 6c 69 74 7 /* sqlit
420b0 65 33 50 61 67 65 4d 61 6c 6c 6f 63 28 29 20 2a e3PageMalloc() *
420c0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
420d0 46 3a 20 52 65 74 72 69 65 76 65 20 74 68 65 20 F: Retrieve the
420e0 6d 75 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 mutex for a data
420f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
42100 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
42110 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
42120 70 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c pointer the [sql
42130 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 ite3_mutex] obje
42140 63 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 ct that .** seri
42150 61 6c 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f alizes access to
42160 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
42170 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e onnection] given
42180 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 in the argument
42190 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 .** when the [th
421a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
421b0 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 Serialized..**
421c0 5e 49 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 ^If the [threadi
421d0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 ng mode] is Sing
421e0 6c 65 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c le-thread or Mul
421f0 74 69 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 ti-thread then t
42200 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 his.** routine r
42210 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
42220 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 inter..*/.SQLITE
42230 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 6d 75 74 _API sqlite3_mut
42240 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d ex *sqlite3_db_m
42250 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a utex(sqlite3*);.
42260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
42270 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 Low-Level Contr
42280 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 ol Of Database F
42290 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 iles.**.** ^The
422a0 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
422b0 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
422c0 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72 65 63 ce makes a direc
422d0 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a t call to the.**
422e0 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
422f0 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b 73 71 thod for the [sq
42300 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
42310 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 ] object associa
42320 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 ted.** with a pa
42330 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
42340 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 e identified by
42350 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
42360 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20 6e 61 6d ent. ^The.** nam
42370 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
42380 65 20 69 73 20 22 6d 61 69 6e 22 20 66 6f 72 20 e is "main" for
42390 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 the main databas
423a0 65 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20 e or "temp" for
423b0 74 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61 the.** TEMP data
423c0 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d base, or the nam
423d0 65 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 e that appears a
423e0 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 fter the AS keyw
423f0 6f 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 ord for.** datab
42400 61 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64 ases that are ad
42410 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41 ded using the [A
42420 54 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61 TTACH] SQL comma
42430 6e 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70 nd..** ^A NULL p
42440 6f 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73 ointer can be us
42450 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 ed in place of "
42460 6d 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74 main" to refer t
42470 6f 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61 o the.** main da
42480 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 tabase file..**
42490 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 ^The third and f
424a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
424b0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
424c0 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 .** are passed d
424d0 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 irectly through
424e0 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e to the second an
424f0 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 d third paramete
42500 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 rs of.** the xFi
42510 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
42520 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 . ^The return v
42530 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c alue of the xFil
42540 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 eControl.** meth
42550 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 od becomes the r
42560 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
42570 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a his routine..**.
42580 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 46 ** ^The SQLITE_F
42590 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
425a0 52 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 R value for the
425b0 6f 70 20 70 61 72 61 6d 65 74 65 72 20 63 61 75 op parameter cau
425c0 73 65 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 ses.** a pointer
425d0 20 74 6f 20 74 68 65 20 75 6e 64 65 72 6c 79 69 to the underlyi
425e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ng [sqlite3_file
425f0 5d 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20 77 ] object to be w
42600 72 69 74 74 65 6e 20 69 6e 74 6f 0a 2a 2a 20 74 ritten into.** t
42610 68 65 20 73 70 61 63 65 20 70 6f 69 6e 74 65 64 he space pointed
42620 20 74 6f 20 62 79 20 74 68 65 20 34 74 68 20 70 to by the 4th p
42630 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 arameter. ^The
42640 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
42650 45 5f 50 4f 49 4e 54 45 52 0a 2a 2a 20 63 61 73 E_POINTER.** cas
42660 65 20 69 73 20 61 20 73 68 6f 72 74 2d 63 69 72 e is a short-cir
42670 63 75 69 74 20 70 61 74 68 20 77 68 69 63 68 20 cuit path which
42680 64 6f 65 73 20 6e 6f 74 20 61 63 74 75 61 6c 6c does not actuall
42690 79 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 y invoke the.**
426a0 75 6e 64 65 72 6c 79 69 6e 67 20 73 71 6c 69 74 underlying sqlit
426b0 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 46 e3_io_methods.xF
426c0 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
426d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
426e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
426f0 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73 r (zDbName) does
42700 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 20 6e not match the n
42710 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 ame of any.** op
42720 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 en database file
42730 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 45 52 , then SQLITE_ER
42740 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65 64 2e ROR is returned.
42750 20 20 5e 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a ^This error.**
42760 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d code is not rem
42770 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c embered and will
42780 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 not be recalled
42790 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 by [sqlite3_err
427a0 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 code()].** or [s
427b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
427c0 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e . The underlyin
427d0 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d g xFileControl m
427e0 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 61 ethod might.** a
427f0 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54 lso return SQLIT
42800 45 5f 45 52 52 4f 52 2e 20 20 54 68 65 72 65 20 E_ERROR. There
42810 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 is no way to dis
42820 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e tinguish between
42830 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 .** an incorrect
42840 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 zDbName and an
42850 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 SQLITE_ERROR ret
42860 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 urn from the und
42870 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 erlying.** xFile
42880 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 0a Control method..
42890 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
428a0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
428b0 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 53 51 4c 49 CKSTATE].*/.SQLI
428c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
428d0 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
428e0 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 sqlite3*, const
428f0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 char *zDbName, i
42900 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt op, void*);..
42910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
42920 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 Testing Interfac
42930 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c e.**.** ^The sql
42940 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
42950 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 l() interface is
42960 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 used to read ou
42970 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 t internal.** st
42980 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e ate of SQLite an
42990 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c d to inject faul
429a0 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 ts into SQLite f
429b0 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 or testing.** pu
429c0 72 70 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 rposes. ^The fi
429d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
429e0 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f an operation co
429f0 64 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e de that determin
42a00 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 es.** the number
42a10 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f , meaning, and o
42a20 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 peration of all
42a30 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d subsequent param
42a40 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 eters..**.** Thi
42a50 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e s interface is n
42a60 6f 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 ot for use by ap
42a70 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 plications. It
42a80 65 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a exists solely.**
42a90 20 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 for verifying t
42aa0 68 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 he correct opera
42ab0 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 tion of the SQLi
42ac0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 te library. Dep
42ad0 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 ending.** on how
42ae0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
42af0 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c ary is compiled,
42b00 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
42b10 6d 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e might not exist.
42b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 .**.** The detai
42b30 6c 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 ls of the operat
42b40 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 ion codes, their
42b50 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 meanings, the p
42b60 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 arameters.** the
42b70 79 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 y take, and what
42b80 20 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c they do are all
42b90 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
42ba0 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 ge without notic
42bb0 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 e..** Unlike mos
42bc0 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 t of the SQLite
42bd0 41 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 API, this functi
42be0 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e on is not guaran
42bf0 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 teed to.** opera
42c00 74 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 te consistently
42c10 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
42c20 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f to the next..*/
42c30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
42c40 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e sqlite3_test_con
42c50 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e trol(int op, ...
42c60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
42c70 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 EF: Testing Inte
42c80 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 rface Operation
42c90 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 Codes.**.** Thes
42ca0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
42cb0 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 the valid operat
42cc0 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 ion code paramet
42cd0 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 ers used.** as t
42ce0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
42cf0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 t to [sqlite3_te
42d00 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a st_control()]..*
42d10 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d *.** These param
42d20 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 eters and their
42d30 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 meanings are sub
42d40 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a ject to change.*
42d50 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 * without notice
42d60 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 . These values
42d70 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 are for testing
42d80 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a purposes only..*
42d90 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 * Applications s
42da0 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e hould not use an
42db0 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d y of these param
42dc0 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 eters or the.**
42dd0 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f [sqlite3_test_co
42de0 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
42df0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ce..*/.#define S
42e00 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 QLITE_TESTCTRL_F
42e10 49 52 53 54 20 20 20 20 20 20 20 20 20 20 20 20 IRST
42e20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
42e30 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
42e40 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 L_PRNG_SAVE
42e50 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
42e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
42e70 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 CTRL_PRNG_RESTOR
42e80 45 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a E 6.
42e90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
42ea0 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 ESTCTRL_PRNG_RES
42eb0 45 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ET
42ec0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
42ed0 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 E_TESTCTRL_BITVE
42ee0 43 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 20 C_TEST
42ef0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
42f00 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 LITE_TESTCTRL_FA
42f10 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 ULT_INSTALL
42f20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 9.#define
42f30 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
42f40 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 _BENIGN_MALLOC_H
42f50 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 OOKS 10.#def
42f60 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
42f70 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 TRL_PENDING_BYTE
42f80 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 11.#
42f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
42fa0 53 54 43 54 52 4c 5f 41 53 53 45 52 54 20 20 20 STCTRL_ASSERT
42fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
42fc0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
42fd0 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 59 53 _TESTCTRL_ALWAYS
42fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42ff0 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 13.#define SQL
43000 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 52 45 53 ITE_TESTCTRL_RES
43010 45 52 56 45 20 20 20 20 20 20 20 20 20 20 20 20 ERVE
43020 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 14.#define
43030 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
43040 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 53 20 20 20 OPTIMIZATIONS
43050 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 15.#defi
43060 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
43070 52 4c 5f 49 53 4b 45 59 57 4f 52 44 20 20 20 20 RL_ISKEYWORD
43080 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 16.#d
43090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
430a0 54 43 54 52 4c 5f 53 43 52 41 54 43 48 4d 41 4c TCTRL_SCRATCHMAL
430b0 4c 4f 43 20 20 20 20 20 20 20 20 20 20 20 31 37 LOC 17
430c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
430d0 54 45 53 54 43 54 52 4c 5f 4c 4f 43 41 4c 54 49 TESTCTRL_LOCALTI
430e0 4d 45 5f 46 41 55 4c 54 20 20 20 20 20 20 20 20 ME_FAULT
430f0 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 18.#define SQLI
43100 54 45 5f 54 45 53 54 43 54 52 4c 5f 45 58 50 4c TE_TESTCTRL_EXPL
43110 41 49 4e 5f 53 54 4d 54 20 20 20 20 20 20 20 20 AIN_STMT
43120 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 19.#define S
43130 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 4c QLITE_TESTCTRL_L
43140 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 AST
43150 20 20 20 20 20 20 20 31 39 0a 0a 2f 2a 0a 2a 2a 19../*.**
43160 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 CAPI3REF: SQLit
43170 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 e Runtime Status
43180 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
43190 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
431a0 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 o retrieve runti
431b0 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d me status inform
431c0 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 ation.** about t
431d0 68 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f he performance o
431e0 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 f SQLite, and op
431f0 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 tionally to rese
43200 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 t various.** hig
43210 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 5e hwater marks. ^
43220 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
43230 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
43240 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 code for.** the
43250 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 specific parame
43260 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 ter to measure.
43270 20 5e 28 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e ^(Recognized in
43280 74 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 teger codes.** a
43290 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b re of the form [
432a0 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 status parameter
432b0 73 20 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 s | SQLITE_STATU
432c0 53 5f 2e 2e 2e 5d 2e 29 5e 0a 2a 2a 20 5e 54 68 S_...].)^.** ^Th
432d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
432e0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 of the parameter
432f0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 74 is returned int
43300 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a 20 o *pCurrent..**
43310 5e 54 68 65 20 68 69 67 68 65 73 74 20 72 65 63 ^The highest rec
43320 6f 72 64 65 64 20 76 61 6c 75 65 20 69 73 20 72 orded value is r
43330 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 69 67 eturned in *pHig
43340 68 77 61 74 65 72 2e 20 20 5e 49 66 20 74 68 65 hwater. ^If the
43350 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 69 73 .** resetFlag is
43360 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 true, then the
43370 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 20 76 highest record v
43380 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 61 66 alue is reset af
43390 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 ter.** *pHighwat
433a0 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 er is written.
433b0 5e 28 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 ^(Some parameter
433c0 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 s do not record
433d0 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 the highest.** v
433e0 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 alue. For those
433f0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e parameters.** n
43400 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 othing is writte
43410 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 n into *pHighwat
43420 65 72 20 61 6e 64 20 74 68 65 20 72 65 73 65 74 er and the reset
43430 46 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e Flag is ignored.
43440 29 5e 0a 2a 2a 20 5e 28 4f 74 68 65 72 20 70 61 )^.** ^(Other pa
43450 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 rameters record
43460 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 only the highwat
43470 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 er mark and not
43480 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 the current.** v
43490 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 alue. For these
434a0 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 latter paramete
434b0 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 rs nothing is wr
434c0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 itten into *pCur
434d0 72 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 rent.)^.**.** ^T
434e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 61 74 75 he sqlite3_statu
434f0 73 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 s() routine retu
43500 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e rns SQLITE_OK on
43510 20 73 75 63 63 65 73 73 20 61 6e 64 20 61 0a 2a success and a.*
43520 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
43530 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 r code] on failu
43540 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 re..**.** This r
43550 6f 75 74 69 6e 65 20 69 73 20 74 68 72 65 61 64 outine is thread
43560 73 61 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20 safe but is not
43570 61 74 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f atomic. This ro
43580 75 74 69 6e 65 20 63 61 6e 20 62 65 0a 2a 2a 20 utine can be.**
43590 63 61 6c 6c 65 64 20 77 68 69 6c 65 20 6f 74 68 called while oth
435a0 65 72 20 74 68 72 65 61 64 73 20 61 72 65 20 72 er threads are r
435b0 75 6e 6e 69 6e 67 20 74 68 65 20 73 61 6d 65 20 unning the same
435c0 6f 72 20 64 69 66 66 65 72 65 6e 74 20 53 51 4c or different SQL
435d0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ite.** interface
435e0 73 2e 20 20 48 6f 77 65 76 65 72 20 74 68 65 20 s. However the
435f0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
43600 69 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 in *pCurrent and
43610 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 .** *pHighwater
43620 72 65 66 6c 65 63 74 20 74 68 65 20 73 74 61 74 reflect the stat
43630 75 73 20 6f 66 20 53 51 4c 69 74 65 20 61 74 20 us of SQLite at
43640 64 69 66 66 65 72 65 6e 74 20 70 6f 69 6e 74 73 different points
43650 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 in time.** and
43660 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 20 74 it is possible t
43670 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 hat another thre
43680 61 64 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 ad might change
43690 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a the parameter.**
436a0 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68 65 20 in between the
436b0 74 69 6d 65 73 20 77 68 65 6e 20 2a 70 43 75 72 times when *pCur
436c0 72 65 6e 74 20 61 6e 64 20 2a 70 48 69 67 68 77 rent and *pHighw
436d0 61 74 65 72 20 61 72 65 20 77 72 69 74 74 65 6e ater are written
436e0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
436f0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 : [sqlite3_db_st
43700 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 atus()].*/.SQLIT
43710 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
43720 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f 70 2c 3_status(int op,
43730 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c 20 int *pCurrent,
43740 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 72 2c int *pHighwater,
43750 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b int resetFlag);
43760 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
43770 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 F: Status Parame
43780 74 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ters.** KEYWORDS
43790 3a 20 7b 73 74 61 74 75 73 20 70 61 72 61 6d 65 : {status parame
437a0 74 65 72 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ters}.**.** Thes
437b0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
437c0 6e 74 73 20 64 65 73 69 67 6e 61 74 65 20 76 61 nts designate va
437d0 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 rious run-time s
437e0 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 tatus parameters
437f0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
43800 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
43810 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a ite3_status()]..
43820 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
43830 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 SQLITE_STATUS_ME
43840 4d 4f 52 59 5f 55 53 45 44 5d 5d 20 5e 28 3c 64 MORY_USED]] ^(<d
43850 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
43860 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e MEMORY_USED</dt>
43870 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
43880 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 63 75 ameter is the cu
43890 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20 rrent amount of
438a0 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 64 20 6f memory checked o
438b0 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ut.** using [sql
438c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
438d0 65 69 74 68 65 72 20 64 69 72 65 63 74 6c 79 20 either directly
438e0 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 2e 20 20 or indirectly.
438f0 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e The.** figure in
43900 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d 61 64 cludes calls mad
43910 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e to [sqlite3_ma
43920 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 65 20 61 lloc()] by the a
43930 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e pplication.** an
43940 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 d internal memor
43950 79 20 75 73 61 67 65 20 62 79 20 74 68 65 20 53 y usage by the S
43960 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
43970 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a Scratch memory.*
43980 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 * controlled by
43990 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
439a0 43 52 41 54 43 48 5d 20 61 6e 64 20 61 75 78 69 CRATCH] and auxi
439b0 6c 69 61 72 79 20 70 61 67 65 2d 63 61 63 68 65 liary page-cache
439c0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 .** memory contr
439d0 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 54 45 olled by [SQLITE
439e0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
439f0 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 E] is not includ
43a00 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61 ed in.** this pa
43a10 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 61 6d rameter. The am
43a20 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 69 73 ount returned is
43a30 20 74 68 65 20 73 75 6d 20 6f 66 20 74 68 65 20 the sum of the
43a40 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 allocation.** si
43a50 7a 65 73 20 61 73 20 72 65 70 6f 72 74 65 64 20 zes as reported
43a60 62 79 20 74 68 65 20 78 53 69 7a 65 20 6d 65 74 by the xSize met
43a70 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f hod in [sqlite3_
43a80 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 mem_methods].</d
43a90 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
43aa0 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f ITE_STATUS_MALLO
43ab0 43 5f 53 49 5a 45 5d 5d 20 5e 28 3c 64 74 3e 53 C_SIZE]] ^(<dt>S
43ac0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c QLITE_STATUS_MAL
43ad0 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a LOC_SIZE</dt>.**
43ae0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
43af0 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 ter records the
43b00 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 largest memory a
43b10 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 llocation reques
43b20 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b t.** handed to [
43b30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
43b40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
43b50 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 65 alloc()] (or the
43b60 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65 ir.** internal e
43b70 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e quivalents). On
43b80 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ly the value ret
43b90 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 urned in the.**
43ba0 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 *pHighwater para
43bb0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
43bc0 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 3_status()] is o
43bd0 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a f interest. .**
43be0 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 The value writt
43bf0 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 en into the *pCu
43c00 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 rrent parameter
43c10 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 is undefined.</d
43c20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
43c30 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f ITE_STATUS_MALLO
43c40 43 5f 43 4f 55 4e 54 5d 5d 20 5e 28 3c 64 74 3e C_COUNT]] ^(<dt>
43c50 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 SQLITE_STATUS_MA
43c60 4c 4c 4f 43 5f 43 4f 55 4e 54 3c 2f 64 74 3e 0a LLOC_COUNT</dt>.
43c70 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
43c80 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 meter records th
43c90 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 65 70 61 e number of sepa
43ca0 72 61 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rate memory allo
43cb0 63 61 74 69 6f 6e 73 0a 2a 2a 20 63 75 72 72 65 cations.** curre
43cc0 6e 74 6c 79 20 63 68 65 63 6b 65 64 20 6f 75 74 ntly checked out
43cd0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
43ce0 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 [SQLITE_STATUS_P
43cf0 41 47 45 43 41 43 48 45 5f 55 53 45 44 5d 5d 20 AGECACHE_USED]]
43d00 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 ^(<dt>SQLITE_STA
43d10 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53 TUS_PAGECACHE_US
43d20 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
43d30 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
43d40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
43d50 20 6f 66 20 70 61 67 65 73 20 75 73 65 64 20 6f of pages used o
43d60 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 61 ut of the.** [pa
43d70 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 gecache memory a
43d80 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74 20 77 llocator] that w
43d90 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 as configured us
43da0 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ing .** [SQLITE_
43db0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
43dc0 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c 75 65 ]. The.** value
43dd0 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20 returned is in
43de0 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20 62 79 pages, not in by
43df0 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a tes.</dd>)^.**.*
43e00 2a 20 5b 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 * [[SQLITE_STATU
43e10 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 S_PAGECACHE_OVER
43e20 46 4c 4f 57 5d 5d 20 0a 2a 2a 20 5e 28 3c 64 74 FLOW]] .** ^(<dt
43e30 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 >SQLITE_STATUS_P
43e40 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f AGECACHE_OVERFLO
43e50 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 W</dt>.** <dd>Th
43e60 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
43e70 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
43e80 6f 66 20 62 79 74 65 73 20 6f 66 20 70 61 67 65 of bytes of page
43e90 20 63 61 63 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 cache.** alloca
43ea0 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 tion which could
43eb0 20 6e 6f 74 20 62 65 20 73 61 74 69 73 66 69 65 not be satisfie
43ec0 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 d by the [SQLITE
43ed0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
43ee0 45 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 E].** buffer and
43ef0 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f where forced to
43f00 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 overflow to [sq
43f10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
43f20 20 20 54 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 The.** returne
43f30 64 20 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 d value includes
43f40 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 allocations tha
43f50 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 t overflowed bec
43f60 61 75 73 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 ause they.** whe
43f70 72 65 20 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 re too large (th
43f80 65 79 20 77 65 72 65 20 6c 61 72 67 65 72 20 74 ey were larger t
43f90 68 61 6e 20 74 68 65 20 22 73 7a 22 20 70 61 72 han the "sz" par
43fa0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 ameter to.** [SQ
43fb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
43fc0 43 41 43 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f CACHE]) and allo
43fd0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 cations that ove
43fe0 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 0a rflowed because.
43ff0 2a 2a 20 6e 6f 20 73 70 61 63 65 20 77 61 73 20 ** no space was
44000 6c 65 66 74 20 69 6e 20 74 68 65 20 70 61 67 65 left in the page
44010 20 63 61 63 68 65 2e 3c 2f 64 64 3e 29 5e 0a 2a cache.</dd>)^.*
44020 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 53 54 *.** [[SQLITE_ST
44030 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 ATUS_PAGECACHE_S
44040 49 5a 45 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 IZE]] ^(<dt>SQLI
44050 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 TE_STATUS_PAGECA
44060 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a CHE_SIZE</dt>.**
44070 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
44080 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 ter records the
44090 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 largest memory a
440a0 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 llocation reques
440b0 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b t.** handed to [
440c0 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 pagecache memory
440d0 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e allocator]. On
440e0 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ly the value ret
440f0 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 urned in the.**
44100 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 *pHighwater para
44110 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
44120 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 3_status()] is o
44130 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a f interest. .**
44140 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 The value writt
44150 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 en into the *pCu
44160 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 rrent parameter
44170 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 is undefined.</d
44180 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
44190 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
441a0 43 48 5f 55 53 45 44 5d 5d 20 5e 28 3c 64 74 3e CH_USED]] ^(<dt>
441b0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 SQLITE_STATUS_SC
441c0 52 41 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a RATCH_USED</dt>.
441d0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
441e0 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 meter returns th
441f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f e number of allo
44200 63 61 74 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 cations used out
44210 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 of the.** [scra
44220 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 tch memory alloc
44230 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 ator] configured
44240 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 using.** [SQLIT
44250 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
44260 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 ]. The value re
44270 74 75 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c turned is in all
44280 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a ocations, not.**
44290 20 69 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63 in bytes. Sinc
442a0 65 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 e a single threa
442b0 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 d may only have
442c0 6f 6e 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f one scratch allo
442d0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 cation.** outsta
442e0 6e 64 69 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 nding at time, t
442f0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 61 6c his parameter al
44300 73 6f 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e so reports the n
44310 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 umber of threads
44320 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72 61 74 63 .** using scratc
44330 68 20 6d 65 6d 6f 72 79 20 61 74 20 74 68 65 20 h memory at the
44340 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 29 same time.</dd>)
44350 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
44360 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f _STATUS_SCRATCH_
44370 4f 56 45 52 46 4c 4f 57 5d 5d 20 5e 28 3c 64 74 OVERFLOW]] ^(<dt
44380 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 >SQLITE_STATUS_S
44390 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c CRATCH_OVERFLOW<
443a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
443b0 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
443c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
443d0 20 62 79 74 65 73 20 6f 66 20 73 63 72 61 74 63 bytes of scratc
443e0 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f h memory.** allo
443f0 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 cation which cou
44400 6c 64 20 6e 6f 74 20 62 65 20 73 61 74 69 73 66 ld not be satisf
44410 69 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 ied by the [SQLI
44420 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
44430 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 H].** buffer and
44440 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f where forced to
44450 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 overflow to [sq
44460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
44470 20 20 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 The values.**
44480 72 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 returned include
44490 20 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 overflows becau
444a0 73 65 20 74 68 65 20 72 65 71 75 65 73 74 65 64 se the requested
444b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 allocation was
444c0 74 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 too.** larger (t
444d0 68 61 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 hat is, because
444e0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c the requested al
444f0 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 location was lar
44500 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 ger than the.**
44510 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 "sz" parameter t
44520 6f 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 o [SQLITE_CONFIG
44530 5f 53 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 _SCRATCH]) and b
44540 65 63 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 ecause no scratc
44550 68 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 h buffer.** slot
44560 73 20 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 s were available
44570 2e 0a 2a 2a 20 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ..** </dd>)^.**.
44580 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 53 54 41 54 ** [[SQLITE_STAT
44590 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 5d US_SCRATCH_SIZE]
445a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 53 ] ^(<dt>SQLITE_S
445b0 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 TATUS_SCRATCH_SI
445c0 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ZE</dt>.** <dd>T
445d0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
445e0 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 cords the larges
445f0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
44600 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 ion request.** h
44610 61 6e 64 65 64 20 74 6f 20 5b 73 63 72 61 74 63 anded to [scratc
44620 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 h memory allocat
44630 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 or]. Only the v
44640 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e alue returned in
44650 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 the.** *pHighwa
44660 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f ter parameter to
44670 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
44680 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 ()] is of intere
44690 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c st. .** The val
446a0 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ue written into
446b0 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 the *pCurrent pa
446c0 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 rameter is undef
446d0 69 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ined.</dd>)^.**.
446e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 53 54 41 54 ** [[SQLITE_STAT
446f0 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 5d US_PARSER_STACK]
44700 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 53 ] ^(<dt>SQLITE_S
44710 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 TATUS_PARSER_STA
44720 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CK</dt>.** <dd>T
44730 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
44740 63 6f 72 64 73 20 74 68 65 20 64 65 65 70 65 73 cords the deepes
44750 74 20 70 61 72 73 65 72 20 73 74 61 63 6b 2e 20 t parser stack.
44760 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20 6d It is only.** m
44770 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53 51 4c eaningful if SQL
44780 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
44790 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d 41 58 with [YYTRACKMAX
447a0 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f 64 64 STACKDEPTH].</dd
447b0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a >)^.** </dl>.**.
447c0 2a 2a 20 4e 65 77 20 73 74 61 74 75 73 20 70 61 ** New status pa
447d0 72 61 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20 rameters may be
447e0 61 64 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20 added from time
447f0 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66 to time..*/.#def
44800 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
44810 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20 S_MEMORY_USED
44820 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
44830 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 SQLITE_STATUS_P
44840 41 47 45 43 41 43 48 45 5f 55 53 45 44 20 20 20 AGECACHE_USED
44850 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
44860 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
44870 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20 CACHE_OVERFLOW
44880 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
44890 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 E_STATUS_SCRATCH
448a0 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 33 0a _USED 3.
448b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
448c0 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 TATUS_SCRATCH_OV
448d0 45 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 64 65 ERFLOW 4.#de
448e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
448f0 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20 US_MALLOC_SIZE
44900 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
44910 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
44920 50 41 52 53 45 52 5f 53 54 41 43 4b 20 20 20 20 PARSER_STACK
44930 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
44940 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
44950 45 43 41 43 48 45 5f 53 49 5a 45 20 20 20 20 20 ECACHE_SIZE
44960 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
44970 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 TE_STATUS_SCRATC
44980 48 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 38 H_SIZE 8
44990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
449a0 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 43 4f STATUS_MALLOC_CO
449b0 55 4e 54 20 20 20 20 20 20 20 20 20 39 0a 0a 2f UNT 9../
449c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
449d0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
449e0 6f 6e 20 53 74 61 74 75 73 0a 2a 2a 0a 2a 2a 20 on Status.**.**
449f0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 ^This interface
44a00 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 is used to retri
44a10 65 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 eve runtime stat
44a20 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a us information .
44a30 2a 2a 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c ** about a singl
44a40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
44a50 65 63 74 69 6f 6e 5d 2e 20 20 5e 54 68 65 20 66 ection]. ^The f
44a60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
44a70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
44a80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 62 6a 65 connection obje
44a90 63 74 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f ct to be interro
44aa0 67 61 74 65 64 2e 20 20 5e 54 68 65 20 73 65 63 gated. ^The sec
44ab0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ond argument.**
44ac0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
44ad0 6e 73 74 61 6e 74 2c 20 74 61 6b 65 6e 20 66 72 nstant, taken fr
44ae0 6f 6d 20 74 68 65 20 73 65 74 20 6f 66 0a 2a 2a om the set of.**
44af0 20 5b 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 [SQLITE_DBSTATU
44b00 53 20 6f 70 74 69 6f 6e 73 5d 2c 20 74 68 61 74 S options], that
44b10 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 .** determines t
44b20 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 he parameter to
44b30 69 6e 74 65 72 72 6f 67 61 74 65 2e 20 20 54 68 interrogate. Th
44b40 65 20 73 65 74 20 6f 66 20 0a 2a 2a 20 5b 53 51 e set of .** [SQ
44b50 4c 49 54 45 5f 44 42 53 54 41 54 55 53 20 6f 70 LITE_DBSTATUS op
44b60 74 69 6f 6e 73 5d 20 69 73 20 6c 69 6b 65 6c 79 tions] is likely
44b70 0a 2a 2a 20 74 6f 20 67 72 6f 77 20 69 6e 20 66 .** to grow in f
44b80 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
44b90 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
44ba0 5e 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c ^The current val
44bb0 75 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 ue of the reques
44bc0 74 65 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ted parameter is
44bd0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
44be0 43 75 72 0a 2a 2a 20 61 6e 64 20 74 68 65 20 68 Cur.** and the h
44bf0 69 67 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e ighest instantan
44c00 65 6f 75 73 20 76 61 6c 75 65 20 69 73 20 77 72 eous value is wr
44c10 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 77 itten into *pHiw
44c20 74 72 2e 20 20 5e 49 66 0a 2a 2a 20 74 68 65 20 tr. ^If.** the
44c30 72 65 73 65 74 46 6c 67 20 69 73 20 74 72 75 65 resetFlg is true
44c40 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67 68 65 , then the highe
44c50 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 st instantaneous
44c60 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 72 65 73 value is.** res
44c70 65 74 20 62 61 63 6b 20 64 6f 77 6e 20 74 6f 20 et back down to
44c80 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
44c90 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e..**.** ^The sq
44ca0 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 lite3_db_status(
44cb0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
44cc0 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 s SQLITE_OK on s
44cd0 75 63 63 65 73 73 20 61 6e 64 20 61 0a 2a 2a 20 uccess and a.**
44ce0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
44cf0 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 code] on failure
44d00 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
44d10 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 : [sqlite3_statu
44d20 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 s()] and [sqlite
44d30 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 3_stmt_status()]
44d40 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
44d50 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 73 int sqlite3_db_s
44d60 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a 2c 20 tatus(sqlite3*,
44d70 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 int op, int *pCu
44d80 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72 2c 20 r, int *pHiwtr,
44d90 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a int resetFlg);..
44da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
44db0 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 Status Parameter
44dc0 73 20 66 6f 72 20 64 61 74 61 62 61 73 65 20 63 s for database c
44dd0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 onnections.** KE
44de0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 49 54 45 5f YWORDS: {SQLITE_
44df0 44 42 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 73 DBSTATUS options
44e00 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
44e10 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
44e20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
44e30 72 20 22 76 65 72 62 73 22 20 74 68 61 74 20 63 r "verbs" that c
44e40 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 0a an be passed as.
44e50 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 ** the second ar
44e60 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
44e70 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
44e80 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
44e90 2a 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 6d *.** New verbs m
44ea0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
44eb0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
44ec0 66 20 53 51 4c 69 74 65 2e 20 45 78 69 73 74 69 f SQLite. Existi
44ed0 6e 67 20 76 65 72 62 73 0a 2a 2a 20 6d 69 67 68 ng verbs.** migh
44ee0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
44ef0 64 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 d. Applications
44f00 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
44f10 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
44f20 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 m.** [sqlite3_db
44f30 5f 73 74 61 74 75 73 28 29 5d 20 74 6f 20 6d 61 _status()] to ma
44f40 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 ke sure that the
44f50 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 0a 2a 2a call worked..**
44f60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 The [sqlite3_db
44f70 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 72 _status()] inter
44f80 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
44f90 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 65 72 72 6f a non-zero erro
44fa0 72 20 63 6f 64 65 0a 2a 2a 20 69 66 20 61 20 64 r code.** if a d
44fb0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
44fc0 6e 73 75 70 70 6f 72 74 65 64 20 76 65 72 62 20 nsupported verb
44fd0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
44fe0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 * <dl>.** [[SQLI
44ff0 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b TE_DBSTATUS_LOOK
45000 41 53 49 44 45 5f 55 53 45 44 5d 5d 20 5e 28 3c ASIDE_USED]] ^(<
45010 64 74 3e 53 51 4c 49 54 45 5f 44 42 53 54 41 54 dt>SQLITE_DBSTAT
45020 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 US_LOOKASIDE_USE
45030 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
45040 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
45050 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
45060 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d of lookaside mem
45070 6f 72 79 20 73 6c 6f 74 73 20 63 75 72 72 65 6e ory slots curren
45080 74 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f tly.** checked o
45090 75 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ut.</dd>)^.**.**
450a0 20 5b 5b 53 51 4c 49 54 45 5f 44 42 53 54 41 54 [[SQLITE_DBSTAT
450b0 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 48 49 54 US_LOOKASIDE_HIT
450c0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
450d0 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 DBSTATUS_LOOKASI
450e0 44 45 5f 48 49 54 3c 2f 64 74 3e 0a 2a 2a 20 3c DE_HIT</dt>.** <
450f0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
45100 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
45110 6d 62 65 72 20 6d 61 6c 6c 6f 63 20 61 74 74 65 mber malloc atte
45120 6d 70 74 73 20 74 68 61 74 20 77 65 72 65 20 0a mpts that were .
45130 2a 2a 20 73 61 74 69 73 66 69 65 64 20 75 73 69 ** satisfied usi
45140 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d ng lookaside mem
45150 6f 72 79 2e 20 4f 6e 6c 79 20 74 68 65 20 68 69 ory. Only the hi
45160 67 68 2d 77 61 74 65 72 20 76 61 6c 75 65 20 69 gh-water value i
45170 73 20 6d 65 61 6e 69 6e 67 66 75 6c 3b 0a 2a 2a s meaningful;.**
45180 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
45190 75 65 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 ue is always zer
451a0 6f 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c o.)^.**.** [[SQL
451b0 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f ITE_DBSTATUS_LOO
451c0 4b 41 53 49 44 45 5f 4d 49 53 53 5f 53 49 5a 45 KASIDE_MISS_SIZE
451d0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 ]].** ^(<dt>SQLI
451e0 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b TE_DBSTATUS_LOOK
451f0 41 53 49 44 45 5f 4d 49 53 53 5f 53 49 5a 45 3c ASIDE_MISS_SIZE<
45200 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
45210 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
45220 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6d 61 ns the number ma
45230 6c 6c 6f 63 20 61 74 74 65 6d 70 74 73 20 74 68 lloc attempts th
45240 61 74 20 6d 69 67 68 74 20 68 61 76 65 0a 2a 2a at might have.**
45250 20 62 65 65 6e 20 73 61 74 69 73 66 69 65 64 20 been satisfied
45260 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 using lookaside
45270 6d 65 6d 6f 72 79 20 62 75 74 20 66 61 69 6c 65 memory but faile
45280 64 20 64 75 65 20 74 6f 20 74 68 65 20 61 6d 6f d due to the amo
45290 75 6e 74 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 unt of.** memory
452a0 20 72 65 71 75 65 73 74 65 64 20 62 65 69 6e 67 requested being
452b0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 larger than the
452c0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 20 lookaside slot
452d0 73 69 7a 65 2e 0a 2a 2a 20 4f 6e 6c 79 20 74 68 size..** Only th
452e0 65 20 68 69 67 68 2d 77 61 74 65 72 20 76 61 6c e high-water val
452f0 75 65 20 69 73 20 6d 65 61 6e 69 6e 67 66 75 6c ue is meaningful
45300 3b 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 ;.** the current
45310 20 76 61 6c 75 65 20 69 73 20 61 6c 77 61 79 73 value is always
45320 20 7a 65 72 6f 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b zero.)^.**.** [
45330 5b 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 [SQLITE_DBSTATUS
45340 5f 4c 4f 4f 4b 41 53 49 44 45 5f 4d 49 53 53 5f _LOOKASIDE_MISS_
45350 46 55 4c 4c 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e FULL]].** ^(<dt>
45360 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
45370 4c 4f 4f 4b 41 53 49 44 45 5f 4d 49 53 53 5f 46 LOOKASIDE_MISS_F
45380 55 4c 4c 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ULL</dt>.** <dd>
45390 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
453a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
453b0 72 20 6d 61 6c 6c 6f 63 20 61 74 74 65 6d 70 74 r malloc attempt
453c0 73 20 74 68 61 74 20 6d 69 67 68 74 20 68 61 76 s that might hav
453d0 65 0a 2a 2a 20 62 65 65 6e 20 73 61 74 69 73 66 e.** been satisf
453e0 69 65 64 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 ied using lookas
453f0 69 64 65 20 6d 65 6d 6f 72 79 20 62 75 74 20 66 ide memory but f
45400 61 69 6c 65 64 20 64 75 65 20 74 6f 20 61 6c 6c ailed due to all
45410 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 lookaside.** me
45420 6d 6f 72 79 20 61 6c 72 65 61 64 79 20 62 65 69 mory already bei
45430 6e 67 20 69 6e 20 75 73 65 2e 0a 2a 2a 20 4f 6e ng in use..** On
45440 6c 79 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 ly the high-wate
45450 72 20 76 61 6c 75 65 20 69 73 20 6d 65 61 6e 69 r value is meani
45460 6e 67 66 75 6c 3b 0a 2a 2a 20 74 68 65 20 63 75 ngful;.** the cu
45470 72 72 65 6e 74 20 76 61 6c 75 65 20 69 73 20 61 rrent value is a
45480 6c 77 61 79 73 20 7a 65 72 6f 2e 29 5e 0a 2a 2a lways zero.)^.**
45490 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 53 .** [[SQLITE_DBS
454a0 54 41 54 55 53 5f 43 41 43 48 45 5f 55 53 45 44 TATUS_CACHE_USED
454b0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
454c0 44 42 53 54 41 54 55 53 5f 43 41 43 48 45 5f 55 DBSTATUS_CACHE_U
454d0 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e SED</dt>.** <dd>
454e0 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
454f0 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f eturns the appro
45500 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 ximate number of
45510 20 6f 66 20 62 79 74 65 73 20 6f 66 20 68 65 61 of bytes of hea
45520 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 75 73 65 64 p.** memory used
45530 20 62 79 20 61 6c 6c 20 70 61 67 65 72 20 63 61 by all pager ca
45540 63 68 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 ches associated
45550 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 with the databas
45560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 0a e connection.)^.
45570 2a 2a 20 5e 54 68 65 20 68 69 67 68 77 61 74 65 ** ^The highwate
45580 72 20 6d 61 72 6b 20 61 73 73 6f 63 69 61 74 65 r mark associate
45590 64 20 77 69 74 68 20 53 51 4c 49 54 45 5f 44 42 d with SQLITE_DB
455a0 53 54 41 54 55 53 5f 43 41 43 48 45 5f 55 53 45 STATUS_CACHE_USE
455b0 44 20 69 73 20 61 6c 77 61 79 73 20 30 2e 0a 2a D is always 0..*
455c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 *.** [[SQLITE_DB
455d0 53 54 41 54 55 53 5f 53 43 48 45 4d 41 5f 55 53 STATUS_SCHEMA_US
455e0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 ED]] ^(<dt>SQLIT
455f0 45 5f 44 42 53 54 41 54 55 53 5f 53 43 48 45 4d E_DBSTATUS_SCHEM
45600 41 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c A_USED</dt>.** <
45610 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
45620 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 r returns the ap
45630 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 proximate number
45640 20 6f 66 20 6f 66 20 62 79 74 65 73 20 6f 66 20 of of bytes of
45650 68 65 61 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 75 heap.** memory u
45660 73 65 64 20 74 6f 20 73 74 6f 72 65 20 74 68 65 sed to store the
45670 20 73 63 68 65 6d 61 20 66 6f 72 20 61 6c 6c 20 schema for all
45680 64 61 74 61 62 61 73 65 73 20 61 73 73 6f 63 69 databases associ
45690 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ated.** with the
456a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2d 20 6d 61 connection - ma
456b0 69 6e 2c 20 74 65 6d 70 2c 20 61 6e 64 20 61 6e in, temp, and an
456c0 79 20 5b 41 54 54 41 43 48 5d 2d 65 64 20 64 61 y [ATTACH]-ed da
456d0 74 61 62 61 73 65 73 2e 29 5e 20 0a 2a 2a 20 5e tabases.)^ .** ^
456e0 54 68 65 20 66 75 6c 6c 20 61 6d 6f 75 6e 74 20 The full amount
456f0 6f 66 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 of memory used b
45700 79 20 74 68 65 20 73 63 68 65 6d 61 73 20 69 73 y the schemas is
45710 20 72 65 70 6f 72 74 65 64 2c 20 65 76 65 6e 20 reported, even
45720 69 66 20 74 68 65 0a 2a 2a 20 73 63 68 65 6d 61 if the.** schema
45730 20 6d 65 6d 6f 72 79 20 69 73 20 73 68 61 72 65 memory is share
45740 64 20 77 69 74 68 20 6f 74 68 65 72 20 64 61 74 d with other dat
45750 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
45760 73 20 64 75 65 20 74 6f 0a 2a 2a 20 5b 73 68 61 s due to.** [sha
45770 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 red cache mode]
45780 62 65 69 6e 67 20 65 6e 61 62 6c 65 64 2e 0a 2a being enabled..*
45790 2a 20 5e 54 68 65 20 68 69 67 68 77 61 74 65 72 * ^The highwater
457a0 20 6d 61 72 6b 20 61 73 73 6f 63 69 61 74 65 64 mark associated
457b0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 44 42 53 with SQLITE_DBS
457c0 54 41 54 55 53 5f 53 43 48 45 4d 41 5f 55 53 45 TATUS_SCHEMA_USE
457d0 44 20 69 73 20 61 6c 77 61 79 73 20 30 2e 0a 2a D is always 0..*
457e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 *.** [[SQLITE_DB
457f0 53 54 41 54 55 53 5f 53 54 4d 54 5f 55 53 45 44 STATUS_STMT_USED
45800 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
45810 44 42 53 54 41 54 55 53 5f 53 54 4d 54 5f 55 53 DBSTATUS_STMT_US
45820 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
45830 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
45840 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 78 turns the approx
45850 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 imate number of
45860 6f 66 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 of bytes of heap
45870 0a 2a 2a 20 61 6e 64 20 6c 6f 6f 6b 61 73 69 64 .** and lookasid
45880 65 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79 e memory used by
45890 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 all prepared st
458a0 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 atements associa
458b0 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 ted with.** the
458c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
458d0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 68 ion.)^.** ^The h
458e0 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 61 73 ighwater mark as
458f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 53 51 sociated with SQ
45900 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 53 54 LITE_DBSTATUS_ST
45910 4d 54 5f 55 53 45 44 20 69 73 20 61 6c 77 61 79 MT_USED is alway
45920 73 20 30 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a s 0..** </dd>.**
45930 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 53 .** [[SQLITE_DBS
45940 54 41 54 55 53 5f 43 41 43 48 45 5f 48 49 54 5d TATUS_CACHE_HIT]
45950 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 44 ] ^(<dt>SQLITE_D
45960 42 53 54 41 54 55 53 5f 43 41 43 48 45 5f 48 49 BSTATUS_CACHE_HI
45970 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 T</dt>.** <dd>Th
45980 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
45990 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
459a0 6f 66 20 70 61 67 65 72 20 63 61 63 68 65 20 68 of pager cache h
459b0 69 74 73 20 74 68 61 74 20 68 61 76 65 0a 2a 2a its that have.**
459c0 20 6f 63 63 75 72 72 65 64 2e 29 5e 20 5e 54 68 occurred.)^ ^Th
459d0 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b e highwater mark
459e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
459f0 20 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 SQLITE_DBSTATUS
45a00 5f 43 41 43 48 45 5f 48 49 54 20 0a 2a 2a 20 69 _CACHE_HIT .** i
45a10 73 20 61 6c 77 61 79 73 20 30 2e 0a 2a 2a 20 3c s always 0..** <
45a20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
45a30 49 54 45 5f 44 42 53 54 41 54 55 53 5f 43 41 43 ITE_DBSTATUS_CAC
45a40 48 45 5f 4d 49 53 53 5d 5d 20 5e 28 3c 64 74 3e HE_MISS]] ^(<dt>
45a50 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
45a60 43 41 43 48 45 5f 4d 49 53 53 3c 2f 64 74 3e 0a CACHE_MISS</dt>.
45a70 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
45a80 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 meter returns th
45a90 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
45aa0 72 20 63 61 63 68 65 20 6d 69 73 73 65 73 20 74 r cache misses t
45ab0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6f 63 63 75 hat have.** occu
45ac0 72 72 65 64 2e 29 5e 20 5e 54 68 65 20 68 69 67 rred.)^ ^The hig
45ad0 68 77 61 74 65 72 20 6d 61 72 6b 20 61 73 73 6f hwater mark asso
45ae0 63 69 61 74 65 64 20 77 69 74 68 20 53 51 4c 49 ciated with SQLI
45af0 54 45 5f 44 42 53 54 41 54 55 53 5f 43 41 43 48 TE_DBSTATUS_CACH
45b00 45 5f 4d 49 53 53 20 0a 2a 2a 20 69 73 20 61 6c E_MISS .** is al
45b10 77 61 79 73 20 30 2e 0a 2a 2a 20 3c 2f 64 64 3e ways 0..** </dd>
45b20 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
45b30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 53 54 fine SQLITE_DBST
45b40 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 ATUS_LOOKASIDE_U
45b50 53 45 44 20 20 20 20 20 20 20 30 0a 23 64 65 66 SED 0.#def
45b60 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 53 54 41 ine SQLITE_DBSTA
45b70 54 55 53 5f 43 41 43 48 45 5f 55 53 45 44 20 20 TUS_CACHE_USED
45b80 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
45b90 6e 65 20 53 51 4c 49 54 45 5f 44 42 53 54 41 54 ne SQLITE_DBSTAT
45ba0 55 53 5f 53 43 48 45 4d 41 5f 55 53 45 44 20 20 US_SCHEMA_USED
45bb0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
45bc0 65 20 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 e SQLITE_DBSTATU
45bd0 53 5f 53 54 4d 54 5f 55 53 45 44 20 20 20 20 20 S_STMT_USED
45be0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
45bf0 20 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 SQLITE_DBSTATUS
45c00 5f 4c 4f 4f 4b 41 53 49 44 45 5f 48 49 54 20 20 _LOOKASIDE_HIT
45c10 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
45c20 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
45c30 4c 4f 4f 4b 41 53 49 44 45 5f 4d 49 53 53 5f 53 LOOKASIDE_MISS_S
45c40 49 5a 45 20 20 35 0a 23 64 65 66 69 6e 65 20 53 IZE 5.#define S
45c50 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c QLITE_DBSTATUS_L
45c60 4f 4f 4b 41 53 49 44 45 5f 4d 49 53 53 5f 46 55 OOKASIDE_MISS_FU
45c70 4c 4c 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 LL 6.#define SQ
45c80 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 43 41 LITE_DBSTATUS_CA
45c90 43 48 45 5f 48 49 54 20 20 20 20 20 20 20 20 20 CHE_HIT
45ca0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
45cb0 49 54 45 5f 44 42 53 54 41 54 55 53 5f 43 41 43 ITE_DBSTATUS_CAC
45cc0 48 45 5f 4d 49 53 53 20 20 20 20 20 20 20 20 20 HE_MISS
45cd0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8.#define SQLI
45ce0 54 45 5f 44 42 53 54 41 54 55 53 5f 4d 41 58 20 TE_DBSTATUS_MAX
45cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
45d00 20 38 20 20 20 2f 2a 20 4c 61 72 67 65 73 74 20 8 /* Largest
45d10 64 65 66 69 6e 65 64 20 44 42 53 54 41 54 55 53 defined DBSTATUS
45d20 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 */.../*.** CAPI
45d30 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 3REF: Prepared S
45d40 74 61 74 65 6d 65 6e 74 20 53 74 61 74 75 73 0a tatement Status.
45d50 2a 2a 0a 2a 2a 20 5e 28 45 61 63 68 20 70 72 65 **.** ^(Each pre
45d60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
45d70 6d 61 69 6e 74 61 69 6e 73 20 76 61 72 69 6f 75 maintains variou
45d80 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d s.** [SQLITE_STM
45d90 54 53 54 41 54 55 53 20 63 6f 75 6e 74 65 72 73 TSTATUS counters
45da0 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 20 74 ] that measure t
45db0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 he number.** of
45dc0 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 65 72 times it has per
45dd0 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 63 20 formed specific
45de0 6f 70 65 72 61 74 69 6f 6e 73 2e 29 5e 20 20 54 operations.)^ T
45df0 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 hese counters ca
45e00 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 n.** be used to
45e10 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 monitor the perf
45e20 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 ormance characte
45e30 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 ristics of the p
45e40 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
45e50 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d ments. For exam
45e60 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 ple, if the numb
45e70 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 er of table step
45e80 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 s greatly exceed
45e90 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
45ea0 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 of table searche
45eb0 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 s or result rows
45ec0 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e , that would ten
45ed0 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a d to indicate.**
45ee0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 that the prepar
45ef0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
45f00 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 using a full tab
45f10 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 le scan rather t
45f20 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e han.** an index.
45f30 20 20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 .**.** ^(This
45f40 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
45f50 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e d to retrieve an
45f60 64 20 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 d reset counter
45f70 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 values from.** a
45f80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
45f90 6d 65 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 ment]. The firs
45fa0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 t argument is th
45fb0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
45fc0 6d 65 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 ment.** object t
45fd0 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
45fe0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 d. The second a
45ff0 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e rgument.** is an
46000 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f integer code fo
46010 72 20 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 r a specific [SQ
46020 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 20 LITE_STMTSTATUS
46030 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20 62 counter].** to b
46040 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 29 e interrogated.)
46050 5e 0a 2a 2a 20 5e 54 68 65 20 63 75 72 72 65 6e ^.** ^The curren
46060 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 t value of the r
46070 65 71 75 65 73 74 65 64 20 63 6f 75 6e 74 65 72 equested counter
46080 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
46090 20 5e 49 66 20 74 68 65 20 72 65 73 65 74 46 6c ^If the resetFl
460a0 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 g is true, then
460b0 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 20 72 the counter is r
460c0 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 66 74 eset to zero aft
460d0 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 er this.** inter
460e0 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 72 6e face call return
460f0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 s..**.** See als
46100 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 o: [sqlite3_stat
46110 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 us()] and [sqlit
46120 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e e3_db_status()].
46130 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
46140 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
46150 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 5f 73 status(sqlite3_s
46160 74 6d 74 2a 2c 20 69 6e 74 20 6f 70 2c 69 6e 74 tmt*, int op,int
46170 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a resetFlg);../*.
46180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 ** CAPI3REF: Sta
46190 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 66 tus Parameters f
461a0 6f 72 20 70 72 65 70 61 72 65 64 20 73 74 61 74 or prepared stat
461b0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 ements.** KEYWOR
461c0 44 53 3a 20 7b 53 51 4c 49 54 45 5f 53 54 4d 54 DS: {SQLITE_STMT
461d0 53 54 41 54 55 53 20 63 6f 75 6e 74 65 72 7d 20 STATUS counter}
461e0 7b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 {SQLITE_STMTSTAT
461f0 55 53 20 63 6f 75 6e 74 65 72 73 7d 0a 2a 2a 0a US counters}.**.
46200 2a 2a 20 54 68 65 73 65 20 70 72 65 70 72 6f 63 ** These preproc
46210 65 73 73 6f 72 20 6d 61 63 72 6f 73 20 64 65 66 essor macros def
46220 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
46230 73 20 74 68 61 74 20 6e 61 6d 65 20 63 6f 75 6e s that name coun
46240 74 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20 61 73 ter.** values as
46250 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
46260 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f e [sqlite3_stmt_
46270 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 72 66 status()] interf
46280 61 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e ace..** The mean
46290 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
462a0 6f 75 73 20 63 6f 75 6e 74 65 72 73 20 61 72 65 ous counters are
462b0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
462c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
462d0 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 ITE_STMTSTATUS_F
462e0 55 4c 4c 53 43 41 4e 5f 53 54 45 50 5d 5d 20 3c ULLSCAN_STEP]] <
462f0 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 dt>SQLITE_STMTST
46300 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 ATUS_FULLSCAN_ST
46310 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e EP</dt>.** <dd>^
46320 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d 62 This is the numb
46330 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
46340 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 65 70 SQLite has step
46350 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a ped forward in.*
46360 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 61 72 * a table as par
46370 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 62 6c t of a full tabl
46380 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e e scan. Large n
46390 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 73 20 umbers for this
463a0 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 counter.** may i
463b0 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 75 6e ndicate opportun
463c0 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 6f 72 ities for perfor
463d0 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e mance improvemen
463e0 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 t through .** ca
463f0 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 reful use of ind
46400 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ices.</dd>.**.**
46410 20 5b 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 [[SQLITE_STMTST
46420 41 54 55 53 5f 53 4f 52 54 5d 5d 20 3c 64 74 3e ATUS_SORT]] <dt>
46430 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 SQLITE_STMTSTATU
46440 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a 20 3c S_SORT</dt>.** <
46450 64 64 3e 5e 54 68 69 73 20 69 73 20 74 68 65 20 dd>^This is the
46460 6e 75 6d 62 65 72 20 6f 66 20 73 6f 72 74 20 6f number of sort o
46470 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 68 perations that h
46480 61 76 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a 2a ave occurred..**
46490 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 A non-zero valu
464a0 65 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 65 e in this counte
464b0 72 20 6d 61 79 20 69 6e 64 69 63 61 74 65 20 61 r may indicate a
464c0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f n opportunity to
464d0 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 .** improvement
464e0 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 68 72 6f performance thro
464f0 75 67 68 20 63 61 72 65 66 75 6c 20 75 73 65 20 ugh careful use
46500 6f 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e of indices.</dd>
46510 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
46520 53 54 4d 54 53 54 41 54 55 53 5f 41 55 54 4f 49 STMTSTATUS_AUTOI
46530 4e 44 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 NDEX]] <dt>SQLIT
46540 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 41 55 54 E_STMTSTATUS_AUT
46550 4f 49 4e 44 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c OINDEX</dt>.** <
46560 64 64 3e 5e 54 68 69 73 20 69 73 20 74 68 65 20 dd>^This is the
46570 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 number of rows i
46580 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 74 72 61 nserted into tra
46590 6e 73 69 65 6e 74 20 69 6e 64 69 63 65 73 20 74 nsient indices t
465a0 68 61 74 0a 2a 2a 20 77 65 72 65 20 63 72 65 61 hat.** were crea
465b0 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ted automaticall
465c0 79 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 y in order to he
465d0 6c 70 20 6a 6f 69 6e 73 20 72 75 6e 20 66 61 73 lp joins run fas
465e0 74 65 72 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 ter..** A non-ze
465f0 72 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 73 ro value in this
46600 20 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 counter may ind
46610 69 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 icate an opportu
46620 6e 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f nity to.** impro
46630 76 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e vement performan
46640 63 65 20 62 79 20 61 64 64 69 6e 67 20 70 65 72 ce by adding per
46650 6d 61 6e 65 6e 74 20 69 6e 64 69 63 65 73 20 74 manent indices t
46660 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6e 65 hat do not.** ne
46670 65 64 20 74 6f 20 62 65 20 72 65 69 6e 69 74 69 ed to be reiniti
46680 61 6c 69 7a 65 64 20 65 61 63 68 20 74 69 6d 65 alized each time
46690 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
466a0 73 20 72 75 6e 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c s run.</dd>.** <
466b0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
466c0 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 SQLITE_STMTSTATU
466d0 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 S_FULLSCAN_STEP
466e0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
466f0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
46700 53 4f 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SORT
46710 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
46720 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 41 55 TE_STMTSTATUS_AU
46730 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 TOINDEX
46740 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 3../*.** CAPI3RE
46750 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 F: Custom Page C
46760 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a ache Object.**.*
46770 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 * The sqlite3_pc
46780 61 63 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 ache type is opa
46790 71 75 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c que. It is impl
467a0 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 emented by.** th
467b0 65 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 e pluggable modu
467c0 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 le. The SQLite
467d0 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 core has no know
467e0 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 ledge of.** its
467f0 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c size or internal
46800 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e structure and n
46810 65 76 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 ever deals with
46820 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 the.** sqlite3_p
46830 63 61 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 cache object exc
46840 65 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 ept by holding a
46850 6e 64 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 nd passing point
46860 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 ers.** to the ob
46870 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ject..**.** See
46880 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
46890 6d 65 74 68 6f 64 73 32 5d 20 66 6f 72 20 61 64 methods2] for ad
468a0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
468b0 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
468c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
468d0 70 63 61 63 68 65 20 73 71 6c 69 74 65 33 5f 70 pcache sqlite3_p
468e0 63 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 cache;../*.** CA
468f0 50 49 33 52 45 46 3a 20 43 75 73 74 6f 6d 20 50 PI3REF: Custom P
46900 61 67 65 20 43 61 63 68 65 20 4f 62 6a 65 63 74 age Cache Object
46910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
46920 65 33 5f 70 63 61 63 68 65 5f 70 61 67 65 20 6f e3_pcache_page o
46930 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
46940 20 61 20 73 69 6e 67 6c 65 20 70 61 67 65 20 69 a single page i
46950 6e 20 74 68 65 0a 2a 2a 20 70 61 67 65 20 63 61 n the.** page ca
46960 63 68 65 2e 20 20 54 68 65 20 70 61 67 65 20 63 che. The page c
46970 61 63 68 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 ache will alloca
46980 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 te instances of
46990 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 this.** object.
469a0 20 56 61 72 69 6f 75 73 20 6d 65 74 68 6f 64 73 Various methods
469b0 20 6f 66 20 74 68 65 20 70 61 67 65 20 63 61 63 of the page cac
469c0 68 65 20 75 73 65 20 70 6f 69 6e 74 65 72 73 20 he use pointers
469d0 74 6f 20 69 6e 73 74 61 6e 63 65 73 0a 2a 2a 20 to instances.**
469e0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 61 of this object a
469f0 73 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 s parameters or
46a00 61 73 20 74 68 65 69 72 20 72 65 74 75 72 6e 20 as their return
46a10 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 value..**.** See
46a20 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
46a30 5f 6d 65 74 68 6f 64 73 32 5d 20 66 6f 72 20 61 _methods2] for a
46a40 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
46a50 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ation..*/.typede
46a60 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
46a70 5f 70 63 61 63 68 65 5f 70 61 67 65 20 73 71 6c _pcache_page sql
46a80 69 74 65 33 5f 70 63 61 63 68 65 5f 70 61 67 65 ite3_pcache_page
46a90 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
46aa0 5f 70 63 61 63 68 65 5f 70 61 67 65 20 7b 0a 20 _pcache_page {.
46ab0 20 76 6f 69 64 20 2a 70 42 75 66 3b 20 20 20 20 void *pBuf;
46ac0 20 20 20 20 2f 2a 20 54 68 65 20 63 6f 6e 74 65 /* The conte
46ad0 6e 74 20 6f 66 20 74 68 65 20 70 61 67 65 20 2a nt of the page *
46ae0 2f 0a 20 20 76 6f 69 64 20 2a 70 45 78 74 72 61 /. void *pExtra
46af0 3b 20 20 20 20 20 20 2f 2a 20 45 78 74 72 61 20 ; /* Extra
46b00 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 73 6f information asso
46b10 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
46b20 70 61 67 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a page */.};../*.*
46b30 2a 20 43 41 50 49 33 52 45 46 3a 20 41 70 70 6c * CAPI3REF: Appl
46b40 69 63 61 74 69 6f 6e 20 44 65 66 69 6e 65 64 20 ication Defined
46b50 50 61 67 65 20 43 61 63 68 65 2e 0a 2a 2a 20 4b Page Cache..** K
46b60 45 59 57 4f 52 44 53 3a 20 7b 70 61 67 65 20 63 EYWORDS: {page c
46b70 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ache}.**.** ^(Th
46b80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
46b90 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
46ba0 47 5f 50 43 41 43 48 45 32 5d 2c 20 2e 2e 2e 29 G_PCACHE2], ...)
46bb0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 0a 2a interface can.*
46bc0 2a 20 72 65 67 69 73 74 65 72 20 61 6e 20 61 6c * register an al
46bd0 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 ternative page c
46be0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
46bf0 69 6f 6e 20 62 79 20 70 61 73 73 69 6e 67 20 69 ion by passing i
46c00 6e 20 61 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 n an .** instanc
46c10 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 e of the sqlite3
46c20 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
46c30 20 73 74 72 75 63 74 75 72 65 2e 29 5e 0a 2a 2a structure.)^.**
46c40 20 49 6e 20 6d 61 6e 79 20 61 70 70 6c 69 63 61 In many applica
46c50 74 69 6f 6e 73 2c 20 6d 6f 73 74 20 6f 66 20 74 tions, most of t
46c60 68 65 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 61 he heap memory a
46c70 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 llocated by .**
46c80 53 51 4c 69 74 65 20 69 73 20 75 73 65 64 20 66 SQLite is used f
46c90 6f 72 20 74 68 65 20 70 61 67 65 20 63 61 63 68 or the page cach
46ca0 65 2e 0a 2a 2a 20 42 79 20 69 6d 70 6c 65 6d 65 e..** By impleme
46cb0 6e 74 69 6e 67 20 61 20 0a 2a 2a 20 63 75 73 74 nting a .** cust
46cc0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 75 73 om page cache us
46cd0 69 6e 67 20 74 68 69 73 20 41 50 49 2c 20 61 6e ing this API, an
46ce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e application can
46cf0 20 62 65 74 74 65 72 20 63 6f 6e 74 72 6f 6c 0a better control.
46d00 2a 2a 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ** the amount of
46d10 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d 65 64 memory consumed
46d20 20 62 79 20 53 51 4c 69 74 65 2c 20 74 68 65 20 by SQLite, the
46d30 77 61 79 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a way in which .**
46d40 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 69 73 20 that memory is
46d50 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20 72 65 allocated and re
46d60 6c 65 61 73 65 64 2c 20 61 6e 64 20 74 68 65 20 leased, and the
46d70 70 6f 6c 69 63 69 65 73 20 75 73 65 64 20 74 6f policies used to
46d80 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 20 65 .** determine e
46d90 78 61 63 74 6c 79 20 77 68 69 63 68 20 70 61 72 xactly which par
46da0 74 73 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 ts of a database
46db0 20 66 69 6c 65 20 61 72 65 20 63 61 63 68 65 64 file are cached
46dc0 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 6f 77 and for .** how
46dd0 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 long..**.** The
46de0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 alternative pag
46df0 65 20 63 61 63 68 65 20 6d 65 63 68 61 6e 69 73 e cache mechanis
46e00 6d 20 69 73 20 61 6e 0a 2a 2a 20 65 78 74 72 65 m is an.** extre
46e10 6d 65 20 6d 65 61 73 75 72 65 20 74 68 61 74 20 me measure that
46e20 69 73 20 6f 6e 6c 79 20 6e 65 65 64 65 64 20 62 is only needed b
46e30 79 20 74 68 65 20 6d 6f 73 74 20 64 65 6d 61 6e y the most deman
46e40 64 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e ding application
46e50 73 2e 0a 2a 2a 20 54 68 65 20 62 75 69 6c 74 2d s..** The built-
46e60 69 6e 20 70 61 67 65 20 63 61 63 68 65 20 69 73 in page cache is
46e70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
46e80 20 6d 6f 73 74 20 75 73 65 73 2e 0a 2a 2a 0a 2a most uses..**.*
46e90 2a 20 5e 28 54 68 65 20 63 6f 6e 74 65 6e 74 73 * ^(The contents
46ea0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
46eb0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 20 pcache_methods2
46ec0 73 74 72 75 63 74 75 72 65 20 61 72 65 20 63 6f structure are co
46ed0 70 69 65 64 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e pied to an.** in
46ee0 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 79 ternal buffer by
46ef0 20 53 51 4c 69 74 65 20 77 69 74 68 69 6e 20 74 SQLite within t
46f00 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 he call to [sqli
46f10 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 20 20 48 65 te3_config]. He
46f20 6e 63 65 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 nce.** the appli
46f30 63 61 74 69 6f 6e 20 6d 61 79 20 64 69 73 63 61 cation may disca
46f40 72 64 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 rd the parameter
46f50 20 61 66 74 65 72 20 74 68 65 20 63 61 6c 6c 20 after the call
46f60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
46f70 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 onfig()] returns
46f80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 74 68 65 20 .)^.**.** [[the
46f90 78 49 6e 69 74 28 29 20 70 61 67 65 20 63 61 63 xInit() page cac
46fa0 68 65 20 6d 65 74 68 6f 64 5d 5d 0a 2a 2a 20 5e he method]].** ^
46fb0 28 54 68 65 20 78 49 6e 69 74 28 29 20 6d 65 74 (The xInit() met
46fc0 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e hod is called on
46fd0 63 65 20 66 6f 72 20 65 61 63 68 20 65 66 66 65 ce for each effe
46fe0 63 74 69 76 65 20 0a 2a 2a 20 63 61 6c 6c 20 74 ctive .** call t
46ff0 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 o [sqlite3_initi
47000 61 6c 69 7a 65 28 29 5d 29 5e 0a 2a 2a 20 28 75 alize()])^.** (u
47010 73 75 61 6c 6c 79 20 6f 6e 6c 79 20 6f 6e 63 65 sually only once
47020 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
47030 74 69 6d 65 20 6f 66 20 74 68 65 20 70 72 6f 63 time of the proc
47040 65 73 73 29 2e 20 5e 28 54 68 65 20 78 49 6e 69 ess). ^(The xIni
47050 74 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 69 73 t().** method is
47060 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f passed a copy o
47070 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 f the sqlite3_pc
47080 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2e 70 41 ache_methods2.pA
47090 72 67 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 20 54 rg value.)^.** T
470a0 68 65 20 69 6e 74 65 6e 74 20 6f 66 20 74 68 65 he intent of the
470b0 20 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 xInit() method
470c0 69 73 20 74 6f 20 73 65 74 20 75 70 20 67 6c 6f is to set up glo
470d0 62 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 bal data structu
470e0 72 65 73 20 0a 2a 2a 20 72 65 71 75 69 72 65 64 res .** required
470f0 20 62 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 by the custom p
47100 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
47110 65 6e 74 61 74 69 6f 6e 2e 20 0a 2a 2a 20 5e 28 entation. .** ^(
47120 49 66 20 74 68 65 20 78 49 6e 69 74 28 29 20 6d If the xInit() m
47130 65 74 68 6f 64 20 69 73 20 4e 55 4c 4c 2c 20 74 ethod is NULL, t
47140 68 65 6e 20 74 68 65 20 0a 2a 2a 20 62 75 69 6c hen the .** buil
47150 74 2d 69 6e 20 64 65 66 61 75 6c 74 20 70 61 67 t-in default pag
47160 65 20 63 61 63 68 65 20 69 73 20 75 73 65 64 20 e cache is used
47170 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 61 instead of the a
47180 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
47190 65 64 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 ed.** page cache
471a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 74 68 65 20 .)^.**.** [[the
471b0 78 53 68 75 74 64 6f 77 6e 28 29 20 70 61 67 65 xShutdown() page
471c0 20 63 61 63 68 65 20 6d 65 74 68 6f 64 5d 5d 0a cache method]].
471d0 2a 2a 20 5e 54 68 65 20 78 53 68 75 74 64 6f 77 ** ^The xShutdow
471e0 6e 28 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 n() method is ca
471f0 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 lled by [sqlite3
47200 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a _shutdown()]..**
47210 20 49 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 It can be used
47220 74 6f 20 63 6c 65 61 6e 20 75 70 20 0a 2a 2a 20 to clean up .**
47230 61 6e 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 any outstanding
47240 72 65 73 6f 75 72 63 65 73 20 62 65 66 6f 72 65 resources before
47250 20 70 72 6f 63 65 73 73 20 73 68 75 74 64 6f 77 process shutdow
47260 6e 2c 20 69 66 20 72 65 71 75 69 72 65 64 2e 0a n, if required..
47270 2a 2a 20 5e 54 68 65 20 78 53 68 75 74 64 6f 77 ** ^The xShutdow
47280 6e 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 n() method may b
47290 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 53 e NULL..**.** ^S
472a0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
472b0 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 73 20 63 lly serializes c
472c0 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 49 6e 69 alls to the xIni
472d0 74 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 73 6f 20 t method,.** so
472e0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 the xInit method
472f0 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 need not be thr
47300 65 61 64 73 61 66 65 2e 20 20 5e 54 68 65 0a 2a eadsafe. ^The.*
47310 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
47320 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
47330 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
47340 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
47350 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
47360 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
47370 61 66 65 20 65 69 74 68 65 72 2e 20 20 41 6c 6c afe either. All
47380 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 20 6d other methods m
47390 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 ust be threadsaf
473a0 65 0a 2a 2a 20 69 6e 20 6d 75 6c 74 69 74 68 72 e.** in multithr
473b0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f eaded applicatio
473c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ns..**.** ^SQLit
473d0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
473e0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
473f0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
47400 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
47410 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
47420 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 utdown()..**.**
47430 5b 5b 74 68 65 20 78 43 72 65 61 74 65 28 29 20 [[the xCreate()
47440 70 61 67 65 20 63 61 63 68 65 20 6d 65 74 68 6f page cache metho
47450 64 73 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ds]].** ^SQLite
47460 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 43 72 65 invokes the xCre
47470 61 74 65 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 ate() method to
47480 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 construct a new
47490 63 61 63 68 65 20 69 6e 73 74 61 6e 63 65 2e 0a cache instance..
474a0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 74 ** SQLite will t
474b0 79 70 69 63 61 6c 6c 79 20 63 72 65 61 74 65 20 ypically create
474c0 6f 6e 65 20 63 61 63 68 65 20 69 6e 73 74 61 6e one cache instan
474d0 63 65 20 66 6f 72 20 65 61 63 68 20 6f 70 65 6e ce for each open
474e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 0a database file,.
474f0 2a 2a 20 74 68 6f 75 67 68 20 74 68 69 73 20 69 ** though this i
47500 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
47510 2e 20 5e 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 . ^The.** first
47520 70 61 72 61 6d 65 74 65 72 2c 20 73 7a 50 61 67 parameter, szPag
47530 65 2c 20 69 73 20 74 68 65 20 73 69 7a 65 20 69 e, is the size i
47540 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 70 n bytes of the p
47550 61 67 65 73 20 74 68 61 74 20 6d 75 73 74 0a 2a ages that must.*
47560 2a 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 * be allocated b
47570 79 20 74 68 65 20 63 61 63 68 65 2e 20 20 5e 73 y the cache. ^s
47580 7a 50 61 67 65 20 77 69 6c 6c 20 61 6c 77 61 79 zPage will alway
47590 73 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f s a power of two
475a0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 65 63 6f 6e . ^The.** secon
475b0 64 20 70 61 72 61 6d 65 74 65 72 20 73 7a 45 78 d parameter szEx
475c0 74 72 61 20 69 73 20 61 20 6e 75 6d 62 65 72 20 tra is a number
475d0 6f 66 20 62 79 74 65 73 20 6f 66 20 65 78 74 72 of bytes of extr
475e0 61 20 73 74 6f 72 61 67 65 20 0a 2a 2a 20 61 73 a storage .** as
475f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 65 61 sociated with ea
47600 63 68 20 70 61 67 65 20 63 61 63 68 65 20 65 6e ch page cache en
47610 74 72 79 2e 20 20 5e 54 68 65 20 73 7a 45 78 74 try. ^The szExt
47620 72 61 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c ra parameter wil
47630 6c 0a 2a 2a 20 61 20 6e 75 6d 62 65 72 20 6c 65 l.** a number le
47640 73 73 20 74 68 61 6e 20 32 35 30 2e 20 20 53 51 ss than 250. SQ
47650 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
47660 65 0a 2a 2a 20 65 78 74 72 61 20 73 7a 45 78 74 e.** extra szExt
47670 72 61 20 62 79 74 65 73 20 6f 6e 20 65 61 63 68 ra bytes on each
47680 20 70 61 67 65 20 74 6f 20 73 74 6f 72 65 20 6d page to store m
47690 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 74 68 etadata about th
476a0 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 e underlying.**
476b0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 6f 6e database page on
476c0 20 64 69 73 6b 2e 20 20 54 68 65 20 76 61 6c 75 disk. The valu
476d0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 73 7a e passed into sz
476e0 45 78 74 72 61 20 64 65 70 65 6e 64 73 0a 2a 2a Extra depends.**
476f0 20 6f 6e 20 74 68 65 20 53 51 4c 69 74 65 20 76 on the SQLite v
47700 65 72 73 69 6f 6e 2c 20 74 68 65 20 74 61 72 67 ersion, the targ
47710 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 et platform, and
47720 20 68 6f 77 20 53 51 4c 69 74 65 20 77 61 73 20 how SQLite was
47730 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 20 5e 54 68 compiled..** ^Th
47740 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
47750 20 74 6f 20 78 43 72 65 61 74 65 28 29 2c 20 62 to xCreate(), b
47760 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20 74 72 Purgeable, is tr
47770 75 65 20 69 66 20 74 68 65 20 63 61 63 68 65 20 ue if the cache
47780 62 65 69 6e 67 0a 2a 2a 20 63 72 65 61 74 65 64 being.** created
47790 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f will be used to
477a0 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 cache database
477b0 70 61 67 65 73 20 6f 66 20 61 20 66 69 6c 65 20 pages of a file
477c0 73 74 6f 72 65 64 20 6f 6e 20 64 69 73 6b 2c 20 stored on disk,
477d0 6f 72 0a 2a 2a 20 66 61 6c 73 65 20 69 66 20 69 or.** false if i
477e0 74 20 69 73 20 75 73 65 64 20 66 6f 72 20 61 6e t is used for an
477f0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
47800 61 73 65 2e 20 54 68 65 20 63 61 63 68 65 20 69 ase. The cache i
47810 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
47820 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 does not have t
47830 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 73 70 o do anything sp
47840 65 63 69 61 6c 20 62 61 73 65 64 20 77 69 74 68 ecial based with
47850 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 62 50 the value of bP
47860 75 72 67 65 61 62 6c 65 3b 0a 2a 2a 20 69 74 20 urgeable;.** it
47870 69 73 20 70 75 72 65 6c 79 20 61 64 76 69 73 6f is purely adviso
47880 72 79 2e 20 20 5e 4f 6e 20 61 20 63 61 63 68 65 ry. ^On a cache
47890 20 77 68 65 72 65 20 62 50 75 72 67 65 61 62 6c where bPurgeabl
478a0 65 20 69 73 20 66 61 6c 73 65 2c 20 53 51 4c 69 e is false, SQLi
478b0 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 te will.** never
478c0 20 69 6e 76 6f 6b 65 20 78 55 6e 70 69 6e 28 29 invoke xUnpin()
478d0 20 65 78 63 65 70 74 20 74 6f 20 64 65 6c 69 62 except to delib
478e0 65 72 61 74 65 6c 79 20 64 65 6c 65 74 65 20 61 erately delete a
478f0 20 70 61 67 65 2e 0a 2a 2a 20 5e 49 6e 20 6f 74 page..** ^In ot
47900 68 65 72 20 77 6f 72 64 73 2c 20 63 61 6c 6c 73 her words, calls
47910 20 74 6f 20 78 55 6e 70 69 6e 28 29 20 6f 6e 20 to xUnpin() on
47920 61 20 63 61 63 68 65 20 77 69 74 68 20 62 50 75 a cache with bPu
47930 72 67 65 61 62 6c 65 20 73 65 74 20 74 6f 0a 2a rgeable set to.*
47940 2a 20 66 61 6c 73 65 20 77 69 6c 6c 20 61 6c 77 * false will alw
47950 61 79 73 20 68 61 76 65 20 74 68 65 20 22 64 69 ays have the "di
47960 73 63 61 72 64 22 20 66 6c 61 67 20 73 65 74 20 scard" flag set
47970 74 6f 20 74 72 75 65 2e 20 20 0a 2a 2a 20 5e 48 to true. .** ^H
47980 65 6e 63 65 2c 20 61 20 63 61 63 68 65 20 63 72 ence, a cache cr
47990 65 61 74 65 64 20 77 69 74 68 20 62 50 75 72 67 eated with bPurg
479a0 65 61 62 6c 65 20 66 61 6c 73 65 20 77 69 6c 6c eable false will
479b0 0a 2a 2a 20 6e 65 76 65 72 20 63 6f 6e 74 61 69 .** never contai
479c0 6e 20 61 6e 79 20 75 6e 70 69 6e 6e 65 64 20 70 n any unpinned p
479d0 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 74 68 ages..**.** [[th
479e0 65 20 78 43 61 63 68 65 73 69 7a 65 28 29 20 70 e xCachesize() p
479f0 61 67 65 20 63 61 63 68 65 20 6d 65 74 68 6f 64 age cache method
47a00 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 78 43 61 63 ]].** ^(The xCac
47a10 68 65 73 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 hesize() method
47a20 6d 61 79 20 62 65 20 63 61 6c 6c 65 64 20 61 74 may be called at
47a30 20 61 6e 79 20 74 69 6d 65 20 62 79 20 53 51 4c any time by SQL
47a40 69 74 65 20 74 6f 20 73 65 74 20 74 68 65 0a 2a ite to set the.*
47a50 2a 20 73 75 67 67 65 73 74 65 64 20 6d 61 78 69 * suggested maxi
47a60 6d 75 6d 20 63 61 63 68 65 2d 73 69 7a 65 20 28 mum cache-size (
47a70 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
47a80 73 74 6f 72 65 64 20 62 79 29 20 74 68 65 20 63 stored by) the c
47a90 61 63 68 65 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 ache.** instance
47aa0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
47ab0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 irst argument. T
47ac0 68 69 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 his is the value
47ad0 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e configured usin
47ae0 67 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 g.** the SQLite
47af0 22 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 "[PRAGMA cache_s
47b00 69 7a 65 5d 22 20 63 6f 6d 6d 61 6e 64 2e 29 5e ize]" command.)^
47b10 20 20 41 73 20 77 69 74 68 20 74 68 65 20 62 50 As with the bP
47b20 75 72 67 65 61 62 6c 65 0a 2a 2a 20 70 61 72 61 urgeable.** para
47b30 6d 65 74 65 72 2c 20 74 68 65 20 69 6d 70 6c 65 meter, the imple
47b40 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 mentation is not
47b50 20 72 65 71 75 69 72 65 64 20 74 6f 20 64 6f 20 required to do
47b60 61 6e 79 74 68 69 6e 67 20 77 69 74 68 20 74 68 anything with th
47b70 69 73 0a 2a 2a 20 76 61 6c 75 65 3b 20 69 74 20 is.** value; it
47b80 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 is advisory only
47b90 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 74 68 65 20 78 50 ..**.** [[the xP
47ba0 61 67 65 63 6f 75 6e 74 28 29 20 70 61 67 65 20 agecount() page
47bb0 63 61 63 68 65 20 6d 65 74 68 6f 64 73 5d 5d 0a cache methods]].
47bc0 2a 2a 20 54 68 65 20 78 50 61 67 65 63 6f 75 6e ** The xPagecoun
47bd0 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 t() method must
47be0 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 return the numbe
47bf0 72 20 6f 66 20 70 61 67 65 73 20 63 75 72 72 65 r of pages curre
47c00 6e 74 6c 79 0a 2a 2a 20 73 74 6f 72 65 64 20 69 ntly.** stored i
47c10 6e 20 74 68 65 20 63 61 63 68 65 2c 20 62 6f 74 n the cache, bot
47c20 68 20 70 69 6e 6e 65 64 20 61 6e 64 20 75 6e 70 h pinned and unp
47c30 69 6e 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 5b 5b inned..** .** [[
47c40 74 68 65 20 78 46 65 74 63 68 28 29 20 70 61 67 the xFetch() pag
47c50 65 20 63 61 63 68 65 20 6d 65 74 68 6f 64 73 5d e cache methods]
47c60 5d 0a 2a 2a 20 54 68 65 20 78 46 65 74 63 68 28 ].** The xFetch(
47c70 29 20 6d 65 74 68 6f 64 20 6c 6f 63 61 74 65 73 ) method locates
47c80 20 61 20 70 61 67 65 20 69 6e 20 74 68 65 20 63 a page in the c
47c90 61 63 68 65 20 61 6e 64 20 72 65 74 75 72 6e 73 ache and returns
47ca0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a a pointer to .*
47cb0 2a 20 61 6e 20 73 71 6c 69 74 65 33 5f 70 63 61 * an sqlite3_pca
47cc0 63 68 65 5f 70 61 67 65 20 6f 62 6a 65 63 74 20 che_page object
47cd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
47ce0 74 68 61 74 20 70 61 67 65 2c 20 6f 72 20 61 20 that page, or a
47cf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
47d00 20 54 68 65 20 70 42 75 66 20 65 6c 65 6d 65 6e The pBuf elemen
47d10 74 20 6f 66 20 74 68 65 20 72 65 74 75 72 6e 65 t of the returne
47d20 64 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 d sqlite3_pcache
47d30 5f 70 61 67 65 20 6f 62 6a 65 63 74 20 77 69 6c _page object wil
47d40 6c 20 62 65 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 l be a.** pointe
47d50 72 20 74 6f 20 61 20 62 75 66 66 65 72 20 6f 66 r to a buffer of
47d60 20 73 7a 50 61 67 65 20 62 79 74 65 73 20 75 73 szPage bytes us
47d70 65 64 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 ed to store the
47d80 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 0a 2a 2a content of a .**
47d90 20 73 69 6e 67 6c 65 20 64 61 74 61 62 61 73 65 single database
47da0 20 70 61 67 65 2e 20 20 54 68 65 20 70 45 78 74 page. The pExt
47db0 72 61 20 65 6c 65 6d 65 6e 74 20 6f 66 20 73 71 ra element of sq
47dc0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 70 61 67 lite3_pcache_pag
47dd0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 20 70 e will be.** a p
47de0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 7a ointer to the sz
47df0 45 78 74 72 61 20 62 79 74 65 73 20 6f 66 20 65 Extra bytes of e
47e00 78 74 72 61 20 73 74 6f 72 61 67 65 20 74 68 61 xtra storage tha
47e10 74 20 53 51 4c 69 74 65 20 68 61 73 20 72 65 71 t SQLite has req
47e20 75 65 73 74 65 64 0a 2a 2a 20 66 6f 72 20 65 61 uested.** for ea
47e30 63 68 20 65 6e 74 72 79 20 69 6e 20 74 68 65 20 ch entry in the
47e40 70 61 67 65 20 63 61 63 68 65 2e 0a 2a 2a 0a 2a page cache..**.*
47e50 2a 20 54 68 65 20 70 61 67 65 20 74 6f 20 62 65 * The page to be
47e60 20 66 65 74 63 68 65 64 20 69 73 20 64 65 74 65 fetched is dete
47e70 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 6b 65 rmined by the ke
47e80 79 2e 20 5e 54 68 65 20 6d 69 6e 69 6d 75 6d 20 y. ^The minimum
47e90 6b 65 79 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 key value.** is
47ea0 31 2e 20 20 41 66 74 65 72 20 69 74 20 68 61 73 1. After it has
47eb0 20 62 65 65 6e 20 72 65 74 72 69 65 76 65 64 20 been retrieved
47ec0 75 73 69 6e 67 20 78 46 65 74 63 68 2c 20 74 68 using xFetch, th
47ed0 65 20 70 61 67 65 20 69 73 20 63 6f 6e 73 69 64 e page is consid
47ee0 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 22 70 ered.** to be "p
47ef0 69 6e 6e 65 64 22 2e 0a 2a 2a 0a 2a 2a 20 49 66 inned"..**.** If
47f00 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 the requested p
47f10 61 67 65 20 69 73 20 61 6c 72 65 61 64 79 20 69 age is already i
47f20 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 n the page cache
47f30 2c 20 74 68 65 6e 20 74 68 65 20 70 61 67 65 20 , then the page
47f40 63 61 63 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 cache.** impleme
47f50 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 ntation must ret
47f60 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f urn a pointer to
47f70 20 74 68 65 20 70 61 67 65 20 62 75 66 66 65 72 the page buffer
47f80 20 77 69 74 68 20 69 74 73 20 63 6f 6e 74 65 6e with its conten
47f90 74 0a 2a 2a 20 69 6e 74 61 63 74 2e 20 20 49 66 t.** intact. If
47fa0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 the requested p
47fb0 61 67 65 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 age is not alrea
47fc0 64 79 20 69 6e 20 74 68 65 20 63 61 63 68 65 2c dy in the cache,
47fd0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 63 then the.** cac
47fe0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
47ff0 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 n should use the
48000 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 63 72 value of the cr
48010 65 61 74 65 46 6c 61 67 0a 2a 2a 20 70 61 72 61 eateFlag.** para
48020 6d 65 74 65 72 20 74 6f 20 68 65 6c 70 20 69 74 meter to help it
48030 20 64 65 74 65 72 6d 69 6e 65 64 20 77 68 61 74 determined what
48040 20 61 63 74 69 6f 6e 20 74 6f 20 74 61 6b 65 3a action to take:
48050 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f .**.** <table bo
48060 72 64 65 72 3d 31 20 77 69 64 74 68 3d 38 35 25 rder=1 width=85%
48070 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a align=center>.*
48080 2a 20 3c 74 72 3e 3c 74 68 3e 20 63 72 65 61 74 * <tr><th> creat
48090 65 46 6c 61 67 20 3c 74 68 3e 20 42 65 68 61 76 eFlag <th> Behav
480a0 69 6f 75 72 20 77 68 65 6e 20 70 61 67 65 20 69 iour when page i
480b0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e s not already in
480c0 20 63 61 63 68 65 0a 2a 2a 20 3c 74 72 3e 3c 74 cache.** <tr><t
480d0 64 3e 20 30 20 3c 74 64 3e 20 44 6f 20 6e 6f 74 d> 0 <td> Do not
480e0 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 20 allocate a new
480f0 70 61 67 65 2e 20 20 52 65 74 75 72 6e 20 4e 55 page. Return NU
48100 4c 4c 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 LL..** <tr><td>
48110 31 20 3c 74 64 3e 20 41 6c 6c 6f 63 61 74 65 20 1 <td> Allocate
48120 61 20 6e 65 77 20 70 61 67 65 20 69 66 20 69 74 a new page if it
48130 20 65 61 73 79 20 61 6e 64 20 63 6f 6e 76 65 6e easy and conven
48140 69 65 6e 74 20 74 6f 20 64 6f 20 73 6f 2e 0a 2a ient to do so..*
48150 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
48160 20 20 4f 74 68 65 72 77 69 73 65 20 72 65 74 75 Otherwise retu
48170 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 20 3c 74 72 3e rn NULL..** <tr>
48180 3c 74 64 3e 20 32 20 3c 74 64 3e 20 4d 61 6b 65 <td> 2 <td> Make
48190 20 65 76 65 72 79 20 65 66 66 6f 72 74 20 74 6f every effort to
481a0 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 20 allocate a new
481b0 70 61 67 65 2e 20 20 4f 6e 6c 79 20 72 65 74 75 page. Only retu
481c0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 rn.**
481d0 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 61 6c NULL if al
481e0 6c 6f 63 61 74 69 6e 67 20 61 20 6e 65 77 20 70 locating a new p
481f0 61 67 65 20 69 73 20 65 66 66 65 63 74 69 76 65 age is effective
48200 6c 79 20 69 6d 70 6f 73 73 69 62 6c 65 2e 0a 2a ly impossible..*
48210 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a * </table>.**.**
48220 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e ^(SQLite will n
48230 6f 72 6d 61 6c 6c 79 20 69 6e 76 6f 6b 65 20 78 ormally invoke x
48240 46 65 74 63 68 28 29 20 77 69 74 68 20 61 20 63 Fetch() with a c
48250 72 65 61 74 65 46 6c 61 67 20 6f 66 20 30 20 6f reateFlag of 0 o
48260 72 20 31 2e 20 20 53 51 4c 69 74 65 0a 2a 2a 20 r 1. SQLite.**
48270 77 69 6c 6c 20 6f 6e 6c 79 20 75 73 65 20 61 20 will only use a
48280 63 72 65 61 74 65 46 6c 61 67 20 6f 66 20 32 20 createFlag of 2
48290 61 66 74 65 72 20 61 20 70 72 69 6f 72 20 63 61 after a prior ca
482a0 6c 6c 20 77 69 74 68 20 61 20 63 72 65 61 74 65 ll with a create
482b0 46 6c 61 67 20 6f 66 20 31 0a 2a 2a 20 66 61 69 Flag of 1.** fai
482c0 6c 65 64 2e 29 5e 20 20 49 6e 20 62 65 74 77 65 led.)^ In betwe
482d0 65 6e 20 74 68 65 20 74 6f 20 78 46 65 74 63 68 en the to xFetch
482e0 28 29 20 63 61 6c 6c 73 2c 20 53 51 4c 69 74 65 () calls, SQLite
482f0 20 6d 61 79 0a 2a 2a 20 61 74 74 65 6d 70 74 20 may.** attempt
48300 74 6f 20 75 6e 70 69 6e 20 6f 6e 65 20 6f 72 20 to unpin one or
48310 6d 6f 72 65 20 63 61 63 68 65 20 70 61 67 65 73 more cache pages
48320 20 62 79 20 73 70 69 6c 6c 69 6e 67 20 74 68 65 by spilling the
48330 20 63 6f 6e 74 65 6e 74 20 6f 66 0a 2a 2a 20 70 content of.** p
48340 69 6e 6e 65 64 20 70 61 67 65 73 20 74 6f 20 64 inned pages to d
48350 69 73 6b 20 61 6e 64 20 73 79 6e 63 68 69 6e 67 isk and synching
48360 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
48370 79 73 74 65 6d 20 64 69 73 6b 20 63 61 63 68 65 ystem disk cache
48380 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 74 68 65 20 78 55 ..**.** [[the xU
48390 6e 70 69 6e 28 29 20 70 61 67 65 20 63 61 63 68 npin() page cach
483a0 65 20 6d 65 74 68 6f 64 5d 5d 0a 2a 2a 20 5e 78 e method]].** ^x
483b0 55 6e 70 69 6e 28 29 20 69 73 20 63 61 6c 6c 65 Unpin() is calle
483c0 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 74 68 d by SQLite with
483d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
483e0 63 75 72 72 65 6e 74 6c 79 20 70 69 6e 6e 65 64 currently pinned
483f0 20 70 61 67 65 0a 2a 2a 20 61 73 20 69 74 73 20 page.** as its
48400 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
48410 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 If the third p
48420 61 72 61 6d 65 74 65 72 2c 20 64 69 73 63 61 72 arameter, discar
48430 64 2c 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a d, is non-zero,.
48440 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 67 65 ** then the page
48450 20 6d 75 73 74 20 62 65 20 65 76 69 63 74 65 64 must be evicted
48460 20 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 2e from the cache.
48470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 69 73 63 .** ^If the disc
48480 61 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ard parameter is
48490 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 .** zero, then t
484a0 68 65 20 70 61 67 65 20 6d 61 79 20 62 65 20 64 he page may be d
484b0 69 73 63 61 72 64 65 64 20 6f 72 20 72 65 74 61 iscarded or reta
484c0 69 6e 65 64 20 61 74 20 74 68 65 20 64 69 73 63 ined at the disc
484d0 72 65 74 69 6f 6e 20 6f 66 0a 2a 2a 20 70 61 67 retion of.** pag
484e0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
484f0 74 61 74 69 6f 6e 2e 20 5e 54 68 65 20 70 61 67 tation. ^The pag
48500 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
48510 74 61 74 69 6f 6e 0a 2a 2a 20 6d 61 79 20 63 68 tation.** may ch
48520 6f 6f 73 65 20 74 6f 20 65 76 69 63 74 20 75 6e oose to evict un
48530 70 69 6e 6e 65 64 20 70 61 67 65 73 20 61 74 20 pinned pages at
48540 61 6e 79 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 any time..**.**
48550 54 68 65 20 63 61 63 68 65 20 6d 75 73 74 20 6e The cache must n
48560 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 72 ot perform any r
48570 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 69 6e eference countin
48580 67 2e 20 41 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 g. A single .**
48590 63 61 6c 6c 20 74 6f 20 78 55 6e 70 69 6e 28 29 call to xUnpin()
485a0 20 75 6e 70 69 6e 73 20 74 68 65 20 70 61 67 65 unpins the page
485b0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
485c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 he number of pri
485d0 6f 72 20 63 61 6c 6c 73 20 0a 2a 2a 20 74 6f 20 or calls .** to
485e0 78 46 65 74 63 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 xFetch()..**.**
485f0 5b 5b 74 68 65 20 78 52 65 6b 65 79 28 29 20 70 [[the xRekey() p
48600 61 67 65 20 63 61 63 68 65 20 6d 65 74 68 6f 64 age cache method
48610 73 5d 5d 0a 2a 2a 20 54 68 65 20 78 52 65 6b 65 s]].** The xReke
48620 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73 y() method is us
48630 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 ed to change the
48640 20 6b 65 79 20 76 61 6c 75 65 20 61 73 73 6f 63 key value assoc
48650 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a iated with the.*
48660 2a 20 70 61 67 65 20 70 61 73 73 65 64 20 61 73 * page passed as
48670 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
48680 6d 65 6e 74 2e 20 49 66 20 74 68 65 20 63 61 63 ment. If the cac
48690 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 he.** previously
486a0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 65 6e 74 contains an ent
486b0 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ry associated wi
486c0 74 68 20 6e 65 77 4b 65 79 2c 20 69 74 20 6d 75 th newKey, it mu
486d0 73 74 20 62 65 0a 2a 2a 20 64 69 73 63 61 72 64 st be.** discard
486e0 65 64 2e 20 5e 41 6e 79 20 70 72 69 6f 72 20 63 ed. ^Any prior c
486f0 61 63 68 65 20 65 6e 74 72 79 20 61 73 73 6f 63 ache entry assoc
48700 69 61 74 65 64 20 77 69 74 68 20 6e 65 77 4b 65 iated with newKe
48710 79 20 69 73 20 67 75 61 72 61 6e 74 65 65 64 20 y is guaranteed
48720 6e 6f 74 0a 2a 2a 20 74 6f 20 62 65 20 70 69 6e not.** to be pin
48730 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ned..**.** When
48740 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 65 SQLite calls the
48750 20 78 54 72 75 6e 63 61 74 65 28 29 20 6d 65 74 xTruncate() met
48760 68 6f 64 2c 20 74 68 65 20 63 61 63 68 65 20 6d hod, the cache m
48770 75 73 74 20 64 69 73 63 61 72 64 20 61 6c 6c 0a ust discard all.
48780 2a 2a 20 65 78 69 73 74 69 6e 67 20 63 61 63 68 ** existing cach
48790 65 20 65 6e 74 72 69 65 73 20 77 69 74 68 20 70 e entries with p
487a0 61 67 65 20 6e 75 6d 62 65 72 73 20 28 6b 65 79 age numbers (key
487b0 73 29 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 s) greater than
487c0 6f 72 20 65 71 75 61 6c 0a 2a 2a 20 74 6f 20 74 or equal.** to t
487d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
487e0 69 4c 69 6d 69 74 20 70 61 72 61 6d 65 74 65 72 iLimit parameter
487f0 20 70 61 73 73 65 64 20 74 6f 20 78 54 72 75 6e passed to xTrun
48800 63 61 74 65 28 29 2e 20 49 66 20 61 6e 79 0a 2a cate(). If any.*
48810 2a 20 6f 66 20 74 68 65 73 65 20 70 61 67 65 73 * of these pages
48820 20 61 72 65 20 70 69 6e 6e 65 64 2c 20 74 68 65 are pinned, the
48830 79 20 61 72 65 20 69 6d 70 6c 69 63 69 74 6c 79 y are implicitly
48840 20 75 6e 70 69 6e 6e 65 64 2c 20 6d 65 61 6e 69 unpinned, meani
48850 6e 67 20 74 68 61 74 0a 2a 2a 20 74 68 65 79 20 ng that.** they
48860 63 61 6e 20 62 65 20 73 61 66 65 6c 79 20 64 69 can be safely di
48870 73 63 61 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b scarded..**.** [
48880 5b 74 68 65 20 78 44 65 73 74 72 6f 79 28 29 20 [the xDestroy()
48890 70 61 67 65 20 63 61 63 68 65 20 6d 65 74 68 6f page cache metho
488a0 64 5d 5d 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 d]].** ^The xDes
488b0 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 20 69 73 troy() method is
488c0 20 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65 20 used to delete
488d0 61 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 a cache allocate
488e0 64 20 62 79 20 78 43 72 65 61 74 65 28 29 2e 0a d by xCreate()..
488f0 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 72 63 65 73 ** All resources
48900 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
48910 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 the specified c
48920 61 63 68 65 20 73 68 6f 75 6c 64 20 62 65 20 66 ache should be f
48930 72 65 65 64 2e 20 5e 41 66 74 65 72 0a 2a 2a 20 reed. ^After.**
48940 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 44 65 73 calling the xDes
48950 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 2c 20 53 troy() method, S
48960 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 72 73 20 QLite considers
48970 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 the [sqlite3_pca
48980 63 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 20 che*].** handle
48990 69 6e 76 61 6c 69 64 2c 20 61 6e 64 20 77 69 6c invalid, and wil
489a0 6c 20 6e 6f 74 20 75 73 65 20 69 74 20 77 69 74 l not use it wit
489b0 68 20 61 6e 79 20 6f 74 68 65 72 20 73 71 6c 69 h any other sqli
489c0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
489d0 64 73 32 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ds2.** functions
489e0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 74 68 65 20 78 53 ..**.** [[the xS
489f0 68 72 69 6e 6b 28 29 20 70 61 67 65 20 63 61 63 hrink() page cac
48a00 68 65 20 6d 65 74 68 6f 64 5d 5d 0a 2a 2a 20 5e he method]].** ^
48a10 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
48a20 68 65 20 78 53 68 72 69 6e 6b 28 29 20 6d 65 74 he xShrink() met
48a30 68 6f 64 20 77 68 65 6e 20 69 74 20 77 61 6e 74 hod when it want
48a40 73 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 s the page cache
48a50 20 74 6f 0a 2a 2a 20 66 72 65 65 20 75 70 20 61 to.** free up a
48a60 73 20 6d 75 63 68 20 6f 66 20 68 65 61 70 20 6d s much of heap m
48a70 65 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62 6c emory as possibl
48a80 65 2e 20 20 54 68 65 20 70 61 67 65 20 63 61 63 e. The page cac
48a90 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
48aa0 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 6f 62 6c 69 n.** is not obli
48ab0 67 61 74 65 64 20 74 6f 20 66 72 65 65 20 61 6e gated to free an
48ac0 79 20 6d 65 6d 6f 72 79 2c 20 62 75 74 20 77 65 y memory, but we
48ad0 6c 6c 2d 62 65 68 61 76 65 64 20 69 6d 70 6c 65 ll-behaved imple
48ae0 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
48af0 64 0a 2a 2a 20 64 6f 20 74 68 65 69 72 20 62 65 d.** do their be
48b00 73 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 st..*/.typedef s
48b10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 truct sqlite3_pc
48b20 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 20 73 71 ache_methods2 sq
48b30 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
48b40 68 6f 64 73 32 3b 0a 73 74 72 75 63 74 20 73 71 hods2;.struct sq
48b50 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
48b60 68 6f 64 73 32 20 7b 0a 20 20 69 6e 74 20 69 56 hods2 {. int iV
48b70 65 72 73 69 6f 6e 3b 0a 20 20 76 6f 69 64 20 2a ersion;. void *
48b80 70 41 72 67 3b 0a 20 20 69 6e 74 20 28 2a 78 49 pArg;. int (*xI
48b90 6e 69 74 29 28 76 6f 69 64 2a 29 3b 0a 20 20 76 nit)(void*);. v
48ba0 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 oid (*xShutdown)
48bb0 28 76 6f 69 64 2a 29 3b 0a 20 20 73 71 6c 69 74 (void*);. sqlit
48bc0 65 33 5f 70 63 61 63 68 65 20 2a 28 2a 78 43 72 e3_pcache *(*xCr
48bd0 65 61 74 65 29 28 69 6e 74 20 73 7a 50 61 67 65 eate)(int szPage
48be0 2c 20 69 6e 74 20 73 7a 45 78 74 72 61 2c 20 69 , int szExtra, i
48bf0 6e 74 20 62 50 75 72 67 65 61 62 6c 65 29 3b 0a nt bPurgeable);.
48c00 20 20 76 6f 69 64 20 28 2a 78 43 61 63 68 65 73 void (*xCaches
48c10 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 ize)(sqlite3_pca
48c20 63 68 65 2a 2c 20 69 6e 74 20 6e 43 61 63 68 65 che*, int nCache
48c30 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
48c40 50 61 67 65 63 6f 75 6e 74 29 28 73 71 6c 69 74 Pagecount)(sqlit
48c50 65 33 5f 70 63 61 63 68 65 2a 29 3b 0a 20 20 73 e3_pcache*);. s
48c60 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 70 61 qlite3_pcache_pa
48c70 67 65 20 2a 28 2a 78 46 65 74 63 68 29 28 73 71 ge *(*xFetch)(sq
48c80 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 lite3_pcache*, u
48c90 6e 73 69 67 6e 65 64 20 6b 65 79 2c 20 69 6e 74 nsigned key, int
48ca0 20 63 72 65 61 74 65 46 6c 61 67 29 3b 0a 20 20 createFlag);.
48cb0 76 6f 69 64 20 28 2a 78 55 6e 70 69 6e 29 28 73 void (*xUnpin)(s
48cc0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 qlite3_pcache*,
48cd0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 70 sqlite3_pcache_p
48ce0 61 67 65 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 age*, int discar
48cf0 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 d);. void (*xRe
48d00 6b 65 79 29 28 73 71 6c 69 74 65 33 5f 70 63 61 key)(sqlite3_pca
48d10 63 68 65 2a 2c 20 73 71 6c 69 74 65 33 5f 70 63 che*, sqlite3_pc
48d20 61 63 68 65 5f 70 61 67 65 2a 2c 20 0a 20 20 20 ache_page*, .
48d30 20 20 20 75 6e 73 69 67 6e 65 64 20 6f 6c 64 4b unsigned oldK
48d40 65 79 2c 20 75 6e 73 69 67 6e 65 64 20 6e 65 77 ey, unsigned new
48d50 4b 65 79 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 Key);. void (*x
48d60 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 Truncate)(sqlite
48d70 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 69 67 3_pcache*, unsig
48d80 6e 65 64 20 69 4c 69 6d 69 74 29 3b 0a 20 20 76 ned iLimit);. v
48d90 6f 69 64 20 28 2a 78 44 65 73 74 72 6f 79 29 28 oid (*xDestroy)(
48da0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 29 sqlite3_pcache*)
48db0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 72 69 ;. void (*xShri
48dc0 6e 6b 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 nk)(sqlite3_pcac
48dd0 68 65 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 he*);.};../*.**
48de0 54 68 69 73 20 69 73 20 74 68 65 20 6f 62 73 6f This is the obso
48df0 6c 65 74 65 20 70 63 61 63 68 65 5f 6d 65 74 68 lete pcache_meth
48e00 6f 64 73 20 6f 62 6a 65 63 74 20 74 68 61 74 20 ods object that
48e10 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 72 65 70 has now been rep
48e20 6c 61 63 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 laced.** by sqli
48e30 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
48e40 64 73 32 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ds2. This objec
48e50 74 20 69 73 20 6e 6f 74 20 75 73 65 64 20 62 79 t is not used by
48e60 20 53 51 4c 69 74 65 2e 20 20 49 74 20 69 73 0a SQLite. It is.
48e70 2a 2a 20 72 65 74 61 69 6e 65 64 20 69 6e 20 74 ** retained in t
48e80 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 66 he header file f
48e90 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
48ea0 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e patibility only.
48eb0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
48ec0 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 ct sqlite3_pcach
48ed0 65 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 e_methods sqlite
48ee0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
48ef0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
48f00 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 _pcache_methods
48f10 7b 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 3b 0a {. void *pArg;.
48f20 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 int (*xInit)(v
48f30 6f 69 64 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a oid*);. void (*
48f40 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a xShutdown)(void*
48f50 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 70 63 61 );. sqlite3_pca
48f60 63 68 65 20 2a 28 2a 78 43 72 65 61 74 65 29 28 che *(*xCreate)(
48f70 69 6e 74 20 73 7a 50 61 67 65 2c 20 69 6e 74 20 int szPage, int
48f80 62 50 75 72 67 65 61 62 6c 65 29 3b 0a 20 20 76 bPurgeable);. v
48f90 6f 69 64 20 28 2a 78 43 61 63 68 65 73 69 7a 65 oid (*xCachesize
48fa0 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 )(sqlite3_pcache
48fb0 2a 2c 20 69 6e 74 20 6e 43 61 63 68 65 73 69 7a *, int nCachesiz
48fc0 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 50 61 67 e);. int (*xPag
48fd0 65 63 6f 75 6e 74 29 28 73 71 6c 69 74 65 33 5f ecount)(sqlite3_
48fe0 70 63 61 63 68 65 2a 29 3b 0a 20 20 76 6f 69 64 pcache*);. void
48ff0 20 2a 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 *(*xFetch)(sqli
49000 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 te3_pcache*, uns
49010 69 67 6e 65 64 20 6b 65 79 2c 20 69 6e 74 20 63 igned key, int c
49020 72 65 61 74 65 46 6c 61 67 29 3b 0a 20 20 76 6f reateFlag);. vo
49030 69 64 20 28 2a 78 55 6e 70 69 6e 29 28 73 71 6c id (*xUnpin)(sql
49040 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f ite3_pcache*, vo
49050 69 64 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 64 id*, int discard
49060 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 6b );. void (*xRek
49070 65 79 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 ey)(sqlite3_pcac
49080 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 69 he*, void*, unsi
49090 67 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 75 6e 73 gned oldKey, uns
490a0 69 67 6e 65 64 20 6e 65 77 4b 65 79 29 3b 0a 20 igned newKey);.
490b0 20 76 6f 69 64 20 28 2a 78 54 72 75 6e 63 61 74 void (*xTruncat
490c0 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e)(sqlite3_pcach
490d0 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 69 4c 69 e*, unsigned iLi
490e0 6d 69 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 mit);. void (*x
490f0 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 Destroy)(sqlite3
49100 5f 70 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 0a _pcache*);.};...
49110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
49120 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 4f 62 Online Backup Ob
49130 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ject.**.** The s
49140 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 qlite3_backup ob
49150 6a 65 63 74 20 72 65 63 6f 72 64 73 20 73 74 61 ject records sta
49160 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 te information a
49170 62 6f 75 74 20 61 6e 20 6f 6e 67 6f 69 6e 67 0a bout an ongoing.
49180 2a 2a 20 6f 6e 6c 69 6e 65 20 62 61 63 6b 75 70 ** online backup
49190 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 5e 54 68 operation. ^Th
491a0 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 e sqlite3_backup
491b0 20 6f 62 6a 65 63 74 20 69 73 20 63 72 65 61 74 object is creat
491c0 65 64 20 62 79 0a 2a 2a 20 61 20 63 61 6c 6c 20 ed by.** a call
491d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b to [sqlite3_back
491e0 75 70 5f 69 6e 69 74 28 29 5d 20 61 6e 64 20 69 up_init()] and i
491f0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 61 s destroyed by a
49200 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
49210 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
49220 73 68 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 sh()]..**.** See
49230 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 Also: [Using th
49240 65 20 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 e SQLite Online
49250 42 61 63 6b 75 70 20 41 50 49 5d 0a 2a 2f 0a 74 Backup API].*/.t
49260 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
49270 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 73 71 6c lite3_backup sql
49280 69 74 65 33 5f 62 61 63 6b 75 70 3b 0a 0a 2f 2a ite3_backup;../*
49290 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
492a0 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 2e line Backup API.
492b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 61 63 6b 75 .**.** The backu
492c0 70 20 41 50 49 20 63 6f 70 69 65 73 20 74 68 65 p API copies the
492d0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 6f 6e 65 20 content of one
492e0 64 61 74 61 62 61 73 65 20 69 6e 74 6f 20 61 6e database into an
492f0 6f 74 68 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 other..** It is
49300 75 73 65 66 75 6c 20 65 69 74 68 65 72 20 66 6f useful either fo
49310 72 20 63 72 65 61 74 69 6e 67 20 62 61 63 6b 75 r creating backu
49320 70 73 20 6f 66 20 64 61 74 61 62 61 73 65 73 20 ps of databases
49330 6f 72 0a 2a 2a 20 66 6f 72 20 63 6f 70 79 69 6e or.** for copyin
49340 67 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 g in-memory data
49350 62 61 73 65 73 20 74 6f 20 6f 72 20 66 72 6f 6d bases to or from
49360 20 70 65 72 73 69 73 74 65 6e 74 20 66 69 6c 65 persistent file
49370 73 2e 20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c s. .**.** See Al
49380 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 so: [Using the S
49390 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 QLite Online Bac
493a0 6b 75 70 20 41 50 49 5d 0a 2a 2a 0a 2a 2a 20 5e kup API].**.** ^
493b0 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 61 20 77 SQLite holds a w
493c0 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
493d0 20 6f 70 65 6e 20 6f 6e 20 74 68 65 20 64 65 73 open on the des
493e0 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 tination databas
493f0 65 20 66 69 6c 65 0a 2a 2a 20 66 6f 72 20 74 68 e file.** for th
49400 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 e duration of th
49410 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
49420 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 75 72 on..** ^The sour
49430 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 ce database is r
49440 65 61 64 2d 6c 6f 63 6b 65 64 20 6f 6e 6c 79 20 ead-locked only
49450 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e while it is bein
49460 67 20 72 65 61 64 3b 0a 2a 2a 20 69 74 20 69 73 g read;.** it is
49470 20 6e 6f 74 20 6c 6f 63 6b 65 64 20 63 6f 6e 74 not locked cont
49480 69 6e 75 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 inuously for the
49490 20 65 6e 74 69 72 65 20 62 61 63 6b 75 70 20 6f entire backup o
494a0 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 peration..** ^Th
494b0 75 73 2c 20 74 68 65 20 62 61 63 6b 75 70 20 6d us, the backup m
494c0 61 79 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 ay be performed
494d0 6f 6e 20 61 20 6c 69 76 65 20 73 6f 75 72 63 65 on a live source
494e0 20 64 61 74 61 62 61 73 65 20 77 69 74 68 6f 75 database withou
494f0 74 0a 2a 2a 20 70 72 65 76 65 6e 74 69 6e 67 20 t.** preventing
49500 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 other database c
49510 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 72 6f 6d 0a onnections from.
49520 2a 2a 20 72 65 61 64 69 6e 67 20 6f 72 20 77 72 ** reading or wr
49530 69 74 69 6e 67 20 74 6f 20 74 68 65 20 73 6f 75 iting to the sou
49540 72 63 65 20 64 61 74 61 62 61 73 65 20 77 68 69 rce database whi
49550 6c 65 20 74 68 65 20 62 61 63 6b 75 70 20 69 73 le the backup is
49560 20 75 6e 64 65 72 77 61 79 2e 0a 2a 2a 20 0a 2a underway..** .*
49570 2a 20 5e 28 54 6f 20 70 65 72 66 6f 72 6d 20 61 * ^(To perform a
49580 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
49590 6e 3a 20 0a 2a 2a 20 20 20 3c 6f 6c 3e 0a 2a 2a n: .** <ol>.**
495a0 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 <li><b>sqli
495b0 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 te3_backup_init(
495c0 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 20 )</b> is called
495d0 6f 6e 63 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 once to initiali
495e0 7a 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ze the.**
495f0 20 20 62 61 63 6b 75 70 2c 20 0a 2a 2a 20 20 20 backup, .**
49600 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 33 <li><b>sqlite3
49610 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 3c 2f _backup_step()</
49620 62 3e 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 b> is called one
49630 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 or more times t
49640 6f 20 74 72 61 6e 73 66 65 72 20 0a 2a 2a 20 20 o transfer .**
49650 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 20 the data
49660 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 between the two
49670 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 66 databases, and f
49680 69 6e 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 3c 6c inally.** <l
49690 69 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 i><b>sqlite3_bac
496a0 6b 75 70 5f 66 69 6e 69 73 68 28 29 3c 2f 62 3e kup_finish()</b>
496b0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
496c0 6c 65 61 73 65 20 61 6c 6c 20 72 65 73 6f 75 72 lease all resour
496d0 63 65 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 ces .**
496e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
496f0 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
49700 74 69 6f 6e 2e 20 0a 2a 2a 20 20 20 3c 2f 6f 6c tion. .** </ol
49710 3e 29 5e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f >)^.** There sho
49720 75 6c 64 20 62 65 20 65 78 61 63 74 6c 79 20 6f uld be exactly o
49730 6e 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ne call to sqlit
49740 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
49750 28 29 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 73 () for each.** s
49760 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
49770 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
49780 5f 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _init()..**.** [
49790 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f [sqlite3_backup_
497a0 69 6e 69 74 28 29 5d 5d 20 3c 62 3e 73 71 6c 69 init()]] <b>sqli
497b0 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 te3_backup_init(
497c0 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 )</b>.**.** ^The
497d0 20 44 20 61 6e 64 20 4e 20 61 72 67 75 6d 65 6e D and N argumen
497e0 74 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 ts to sqlite3_ba
497f0 63 6b 75 70 5f 69 6e 69 74 28 44 2c 4e 2c 53 2c ckup_init(D,N,S,
49800 4d 29 20 61 72 65 20 74 68 65 20 0a 2a 2a 20 5b M) are the .** [
49810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
49820 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 ion] associated
49830 77 69 74 68 20 74 68 65 20 64 65 73 74 69 6e 61 with the destina
49840 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 0a 2a tion database .*
49850 2a 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 * and the databa
49860 73 65 20 6e 61 6d 65 2c 20 72 65 73 70 65 63 74 se name, respect
49870 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 64 ively..** ^The d
49880 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 atabase name is
49890 22 6d 61 69 6e 22 20 66 6f 72 20 74 68 65 20 6d "main" for the m
498a0 61 69 6e 20 64 61 74 61 62 61 73 65 2c 20 22 74 ain database, "t
498b0 65 6d 70 22 20 66 6f 72 20 74 68 65 0a 2a 2a 20 emp" for the.**
498c0 74 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 temporary databa
498d0 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d 65 20 se, or the name
498e0 73 70 65 63 69 66 69 65 64 20 61 66 74 65 72 20 specified after
498f0 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20 69 the AS keyword i
49900 6e 0a 2a 2a 20 61 6e 20 5b 41 54 54 41 43 48 5d n.** an [ATTACH]
49910 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 61 statement for a
49920 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 n attached datab
49930 61 73 65 2e 0a 2a 2a 20 5e 54 68 65 20 53 20 61 ase..** ^The S a
49940 6e 64 20 4d 20 61 72 67 75 6d 65 6e 74 73 20 70 nd M arguments p
49950 61 73 73 65 64 20 74 6f 20 0a 2a 2a 20 73 71 6c assed to .** sql
49960 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 ite3_backup_init
49970 28 44 2c 4e 2c 53 2c 4d 29 20 69 64 65 6e 74 69 (D,N,S,M) identi
49980 66 79 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 fy the [database
49990 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
499a0 61 6e 64 20 64 61 74 61 62 61 73 65 20 6e 61 6d and database nam
499b0 65 20 6f 66 20 74 68 65 20 73 6f 75 72 63 65 20 e of the source
499c0 64 61 74 61 62 61 73 65 2c 20 72 65 73 70 65 63 database, respec
499d0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 tively..** ^The
499e0 73 6f 75 72 63 65 20 61 6e 64 20 64 65 73 74 69 source and desti
499f0 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 nation [database
49a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 28 70 connections] (p
49a10 61 72 61 6d 65 74 65 72 73 20 53 20 61 6e 64 20 arameters S and
49a20 44 29 0a 2a 2a 20 6d 75 73 74 20 62 65 20 64 69 D).** must be di
49a30 66 66 65 72 65 6e 74 20 6f 72 20 65 6c 73 65 20 fferent or else
49a40 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
49a50 6e 69 74 28 44 2c 4e 2c 53 2c 4d 29 20 77 69 6c nit(D,N,S,M) wil
49a60 6c 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 61 l fail with.** a
49a70 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e n error..**.** ^
49a80 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 If an error occu
49a90 72 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 rs within sqlite
49aa0 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 44 2c 3_backup_init(D,
49ab0 4e 2c 53 2c 4d 29 2c 20 74 68 65 6e 20 4e 55 4c N,S,M), then NUL
49ac0 4c 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 L is.** returned
49ad0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 63 6f and an error co
49ae0 64 65 20 61 6e 64 20 65 72 72 6f 72 20 6d 65 73 de and error mes
49af0 73 61 67 65 20 61 72 65 20 73 74 6f 72 65 64 20 sage are stored
49b00 69 6e 20 74 68 65 0a 2a 2a 20 64 65 73 74 69 6e in the.** destin
49b10 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ation [database
49b20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a connection] D..*
49b30 2a 20 5e 54 68 65 20 65 72 72 6f 72 20 63 6f 64 * ^The error cod
49b40 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 66 6f e and message fo
49b50 72 20 74 68 65 20 66 61 69 6c 65 64 20 63 61 6c r the failed cal
49b60 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
49b70 6b 75 70 5f 69 6e 69 74 28 29 0a 2a 2a 20 63 61 kup_init().** ca
49b80 6e 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 n be retrieved u
49b90 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
49ba0 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 3_errcode()], [s
49bb0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
49bc0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c , and/or.** [sql
49bd0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
49be0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 5e functions..** ^
49bf0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
49c00 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
49c10 6b 75 70 5f 69 6e 69 74 28 29 20 72 65 74 75 72 kup_init() retur
49c20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
49c30 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 an.** [sqlite3_b
49c40 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 2e 0a 2a ackup] object..*
49c50 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
49c60 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 20 6d backup] object m
49c70 61 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ay be used with
49c80 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b the sqlite3_back
49c90 75 70 5f 73 74 65 70 28 29 20 61 6e 64 0a 2a 2a up_step() and.**
49ca0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
49cb0 66 69 6e 69 73 68 28 29 20 66 75 6e 63 74 69 6f finish() functio
49cc0 6e 73 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 ns to perform th
49cd0 65 20 73 70 65 63 69 66 69 65 64 20 62 61 63 6b e specified back
49ce0 75 70 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e up .** operation
49cf0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 ..**.** [[sqlite
49d00 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 5d 3_backup_step()]
49d10 5d 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 ] <b>sqlite3_bac
49d20 6b 75 70 5f 73 74 65 70 28 29 3c 2f 62 3e 0a 2a kup_step()</b>.*
49d30 2a 0a 2a 2a 20 5e 46 75 6e 63 74 69 6f 6e 20 73 *.** ^Function s
49d40 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
49d50 65 70 28 42 2c 4e 29 20 77 69 6c 6c 20 63 6f 70 ep(B,N) will cop
49d60 79 20 75 70 20 74 6f 20 4e 20 70 61 67 65 73 20 y up to N pages
49d70 62 65 74 77 65 65 6e 20 0a 2a 2a 20 74 68 65 20 between .** the
49d80 73 6f 75 72 63 65 20 61 6e 64 20 64 65 73 74 69 source and desti
49d90 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 73 nation databases
49da0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 5b 73 specified by [s
49db0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
49dc0 62 6a 65 63 74 20 42 2e 0a 2a 2a 20 5e 49 66 20 bject B..** ^If
49dd0 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 N is negative, a
49de0 6c 6c 20 72 65 6d 61 69 6e 69 6e 67 20 73 6f 75 ll remaining sou
49df0 72 63 65 20 70 61 67 65 73 20 61 72 65 20 63 6f rce pages are co
49e00 70 69 65 64 2e 20 0a 2a 2a 20 5e 49 66 20 73 71 pied. .** ^If sq
49e10 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
49e20 70 28 42 2c 4e 29 20 73 75 63 63 65 73 73 66 75 p(B,N) successfu
49e30 6c 6c 79 20 63 6f 70 69 65 73 20 4e 20 70 61 67 lly copies N pag
49e40 65 73 20 61 6e 64 20 74 68 65 72 65 0a 2a 2a 20 es and there.**
49e50 61 72 65 20 73 74 69 6c 6c 20 6d 6f 72 65 20 70 are still more p
49e60 61 67 65 73 20 74 6f 20 62 65 20 63 6f 70 69 65 ages to be copie
49e70 64 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 d, then the func
49e80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 tion returns [SQ
49e90 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 LITE_OK]..** ^If
49ea0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
49eb0 73 74 65 70 28 42 2c 4e 29 20 73 75 63 63 65 73 step(B,N) succes
49ec0 73 66 75 6c 6c 79 20 66 69 6e 69 73 68 65 73 20 sfully finishes
49ed0 63 6f 70 79 69 6e 67 20 61 6c 6c 20 70 61 67 65 copying all page
49ee0 73 0a 2a 2a 20 66 72 6f 6d 20 73 6f 75 72 63 65 s.** from source
49ef0 20 74 6f 20 64 65 73 74 69 6e 61 74 69 6f 6e 2c to destination,
49f00 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 then it returns
49f10 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a [SQLITE_DONE]..
49f20 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 ** ^If an error
49f30 6f 63 63 75 72 73 20 77 68 69 6c 65 20 72 75 6e occurs while run
49f40 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 62 61 63 ning sqlite3_bac
49f50 6b 75 70 5f 73 74 65 70 28 42 2c 4e 29 2c 0a 2a kup_step(B,N),.*
49f60 2a 20 74 68 65 6e 20 61 6e 20 5b 65 72 72 6f 72 * then an [error
49f70 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
49f80 65 64 2e 20 5e 41 73 20 77 65 6c 6c 20 61 73 20 ed. ^As well as
49f90 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 0a [SQLITE_OK] and.
49fa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
49fb0 2c 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 , a call to sqli
49fc0 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
49fd0 29 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 51 ) may return [SQ
49fe0 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2c 0a LITE_READONLY],.
49ff0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ** [SQLITE_NOMEM
4a000 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ], [SQLITE_BUSY]
4a010 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 , [SQLITE_LOCKED
4a020 5d 2c 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c ], or an.** [SQL
4a030 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 ITE_IOERR_ACCESS
4a040 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f | SQLITE_IOERR_
4a050 58 58 58 5d 20 65 78 74 65 6e 64 65 64 20 65 72 XXX] extended er
4a060 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 ror code..**.**
4a070 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 62 61 ^(The sqlite3_ba
4a080 63 6b 75 70 5f 73 74 65 70 28 29 20 6d 69 67 68 ckup_step() migh
4a090 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 t return [SQLITE
4a0a0 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 66 0a 2a 2a _READONLY] if.**
4a0b0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 <ol>.** <li> th
4a0c0 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 e destination da
4a0d0 74 61 62 61 73 65 20 77 61 73 20 6f 70 65 6e 65 tabase was opene
4a0e0 64 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 6f 72 0a d read-only, or.
4a0f0 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 64 65 73 74 ** <li> the dest
4a100 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
4a110 20 69 73 20 75 73 69 6e 67 20 77 72 69 74 65 2d is using write-
4a120 61 68 65 61 64 2d 6c 6f 67 20 6a 6f 75 72 6e 61 ahead-log journa
4a130 6c 69 6e 67 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ling.** and the
4a140 64 65 73 74 69 6e 61 74 69 6f 6e 20 61 6e 64 20 destination and
4a150 73 6f 75 72 63 65 20 70 61 67 65 20 73 69 7a 65 source page size
4a160 73 20 64 69 66 66 65 72 2c 20 6f 72 0a 2a 2a 20 s differ, or.**
4a170 3c 6c 69 3e 20 74 68 65 20 64 65 73 74 69 6e 61 <li> the destina
4a180 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 69 73 tion database is
4a190 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 an in-memory da
4a1a0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 0a 2a tabase and the.*
4a1b0 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 61 6e * destination an
4a1c0 64 20 73 6f 75 72 63 65 20 70 61 67 65 20 73 69 d source page si
4a1d0 7a 65 73 20 64 69 66 66 65 72 2e 0a 2a 2a 20 3c zes differ..** <
4a1e0 2f 6f 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 /ol>)^.**.** ^If
4a1f0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
4a200 73 74 65 70 28 29 20 63 61 6e 6e 6f 74 20 6f 62 step() cannot ob
4a210 74 61 69 6e 20 61 20 72 65 71 75 69 72 65 64 20 tain a required
4a220 66 69 6c 65 2d 73 79 73 74 65 6d 20 6c 6f 63 6b file-system lock
4a230 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 73 , then.** the [s
4a240 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
4a250 6c 65 72 20 7c 20 62 75 73 79 2d 68 61 6e 64 6c ler | busy-handl
4a260 65 72 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 er function].**
4a270 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 66 20 6f is invoked (if o
4a280 6e 65 20 69 73 20 73 70 65 63 69 66 69 65 64 29 ne is specified)
4a290 2e 20 5e 49 66 20 74 68 65 20 0a 2a 2a 20 62 75 . ^If the .** bu
4a2a0 73 79 2d 68 61 6e 64 6c 65 72 20 72 65 74 75 72 sy-handler retur
4a2b0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 62 65 66 6f ns non-zero befo
4a2c0 72 65 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 61 re the lock is a
4a2d0 76 61 69 6c 61 62 6c 65 2c 20 74 68 65 6e 20 0a vailable, then .
4a2e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
4a2f0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 is returned to
4a300 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 49 6e 20 the caller. ^In
4a310 74 68 69 73 20 63 61 73 65 20 74 68 65 20 63 61 this case the ca
4a320 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
4a330 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 _backup_step() c
4a340 61 6e 20 62 65 20 72 65 74 72 69 65 64 20 6c 61 an be retried la
4a350 74 65 72 2e 20 5e 49 66 20 74 68 65 20 73 6f 75 ter. ^If the sou
4a360 72 63 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 rce.** [database
4a370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
4a380 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 74 6f is being used to
4a390 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 6f write to the so
4a3a0 75 72 63 65 20 64 61 74 61 62 61 73 65 20 77 68 urce database wh
4a3b0 65 6e 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 en sqlite3_backu
4a3c0 70 5f 73 74 65 70 28 29 0a 2a 2a 20 69 73 20 63 p_step().** is c
4a3d0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 5b 53 51 4c alled, then [SQL
4a3e0 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 69 73 20 72 ITE_LOCKED] is r
4a3f0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
4a400 65 6c 79 2e 20 5e 41 67 61 69 6e 2c 20 69 6e 20 ely. ^Again, in
4a410 74 68 69 73 0a 2a 2a 20 63 61 73 65 20 74 68 65 this.** case the
4a420 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
4a430 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 _backup_step() c
4a440 61 6e 20 62 65 20 72 65 74 72 69 65 64 20 6c 61 an be retried la
4a450 74 65 72 20 6f 6e 2e 20 5e 28 49 66 0a 2a 2a 20 ter on. ^(If.**
4a460 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 [SQLITE_IOERR_AC
4a470 43 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f CESS | SQLITE_IO
4a480 45 52 52 5f 58 58 58 5d 2c 20 5b 53 51 4c 49 54 ERR_XXX], [SQLIT
4a490 45 5f 4e 4f 4d 45 4d 5d 2c 20 6f 72 0a 2a 2a 20 E_NOMEM], or.**
4a4a0 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
4a4b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 74 ] is returned, t
4a4c0 68 65 6e 20 0a 2a 2a 20 74 68 65 72 65 20 69 73 hen .** there is
4a4d0 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 72 65 74 no point in ret
4a4e0 72 79 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74 rying the call t
4a4f0 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
4a500 5f 73 74 65 70 28 29 2e 20 54 68 65 73 65 20 0a _step(). These .
4a510 2a 2a 20 65 72 72 6f 72 73 20 61 72 65 20 63 6f ** errors are co
4a520 6e 73 69 64 65 72 65 64 20 66 61 74 61 6c 2e 29 nsidered fatal.)
4a530 5e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ^ The applicati
4a540 6f 6e 20 6d 75 73 74 20 61 63 63 65 70 74 20 0a on must accept .
4a550 2a 2a 20 74 68 61 74 20 74 68 65 20 62 61 63 6b ** that the back
4a560 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 68 61 73 up operation has
4a570 20 66 61 69 6c 65 64 20 61 6e 64 20 70 61 73 73 failed and pass
4a580 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
4a590 61 74 69 6f 6e 20 68 61 6e 64 6c 65 20 0a 2a 2a ation handle .**
4a5a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
4a5b0 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 backup_finish()
4a5c0 74 6f 20 72 65 6c 65 61 73 65 20 61 73 73 6f 63 to release assoc
4a5d0 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 2e iated resources.
4a5e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
4a5f0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 t call to sqlite
4a600 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
4a610 6f 62 74 61 69 6e 73 20 61 6e 20 65 78 63 6c 75 obtains an exclu
4a620 73 69 76 65 20 6c 6f 63 6b 0a 2a 2a 20 6f 6e 20 sive lock.** on
4a630 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 the destination
4a640 66 69 6c 65 2e 20 5e 54 68 65 20 65 78 63 6c 75 file. ^The exclu
4a650 73 69 76 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 sive lock is not
4a660 20 72 65 6c 65 61 73 65 64 20 75 6e 74 69 6c 20 released until
4a670 65 69 74 68 65 72 20 0a 2a 2a 20 73 71 6c 69 74 either .** sqlit
4a680 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
4a690 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 72 20 () is called or
4a6a0 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
4a6b0 74 69 6f 6e 20 69 73 20 63 6f 6d 70 6c 65 74 65 tion is complete
4a6c0 20 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 .** and sqlite3
4a6d0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 72 _backup_step() r
4a6e0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 eturns [SQLITE_D
4a6f0 4f 4e 45 5d 2e 20 20 5e 45 76 65 72 79 20 63 61 ONE]. ^Every ca
4a700 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
4a710 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 6f _backup_step() o
4a720 62 74 61 69 6e 73 20 61 20 5b 73 68 61 72 65 64 btains a [shared
4a730 20 6c 6f 63 6b 5d 20 6f 6e 20 74 68 65 20 73 6f lock] on the so
4a740 75 72 63 65 20 64 61 74 61 62 61 73 65 20 74 68 urce database th
4a750 61 74 0a 2a 2a 20 6c 61 73 74 73 20 66 6f 72 20 at.** lasts for
4a760 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 the duration of
4a770 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b the sqlite3_back
4a780 75 70 5f 73 74 65 70 28 29 20 63 61 6c 6c 2e 0a up_step() call..
4a790 2a 2a 20 5e 42 65 63 61 75 73 65 20 74 68 65 20 ** ^Because the
4a7a0 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 source database
4a7b0 69 73 20 6e 6f 74 20 6c 6f 63 6b 65 64 20 62 65 is not locked be
4a7c0 74 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 0a 2a tween calls to.*
4a7d0 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 * sqlite3_backup
4a7e0 5f 73 74 65 70 28 29 2c 20 74 68 65 20 73 6f 75 _step(), the sou
4a7f0 72 63 65 20 64 61 74 61 62 61 73 65 20 6d 61 79 rce database may
4a800 20 62 65 20 6d 6f 64 69 66 69 65 64 20 6d 69 64 be modified mid
4a810 2d 77 61 79 0a 2a 2a 20 74 68 72 6f 75 67 68 20 -way.** through
4a820 74 68 65 20 62 61 63 6b 75 70 20 70 72 6f 63 65 the backup proce
4a830 73 73 2e 20 20 5e 49 66 20 74 68 65 20 73 6f 75 ss. ^If the sou
4a840 72 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 rce database is
4a850 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a modified by an.*
4a860 2a 20 65 78 74 65 72 6e 61 6c 20 70 72 6f 63 65 * external proce
4a870 73 73 20 6f 72 20 76 69 61 20 61 20 64 61 74 61 ss or via a data
4a880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
4a890 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f other than the o
4a8a0 6e 65 20 62 65 69 6e 67 0a 2a 2a 20 75 73 65 64 ne being.** used
4a8b0 20 62 79 20 74 68 65 20 62 61 63 6b 75 70 20 6f by the backup o
4a8c0 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 74 peration, then t
4a8d0 68 65 20 62 61 63 6b 75 70 20 77 69 6c 6c 20 62 he backup will b
4a8e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
4a8f0 2a 2a 20 72 65 73 74 61 72 74 65 64 20 62 79 20 ** restarted by
4a900 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f the next call to
4a910 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
4a920 73 74 65 70 28 29 2e 20 5e 49 66 20 74 68 65 20 step(). ^If the
4a930 73 6f 75 72 63 65 20 0a 2a 2a 20 64 61 74 61 62 source .** datab
4a940 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 ase is modified
4a950 62 79 20 74 68 65 20 75 73 69 6e 67 20 74 68 65 by the using the
4a960 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
4a970 6f 6e 6e 65 63 74 69 6f 6e 20 61 73 20 69 73 20 onnection as is
4a980 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 62 used.** by the b
4a990 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c ackup operation,
4a9a0 20 74 68 65 6e 20 74 68 65 20 62 61 63 6b 75 70 then the backup
4a9b0 20 64 61 74 61 62 61 73 65 20 69 73 20 61 75 74 database is aut
4a9c0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 75 70 omatically.** up
4a9d0 64 61 74 65 64 20 61 74 20 74 68 65 20 73 61 6d dated at the sam
4a9e0 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b e time..**.** [[
4a9f0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 sqlite3_backup_f
4aa00 69 6e 69 73 68 28 29 5d 5d 20 3c 62 3e 73 71 6c inish()]] <b>sql
4aa10 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
4aa20 73 68 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 sh()</b>.**.** W
4aa30 68 65 6e 20 73 71 6c 69 74 65 33 5f 62 61 63 6b hen sqlite3_back
4aa40 75 70 5f 73 74 65 70 28 29 20 68 61 73 20 72 65 up_step() has re
4aa50 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 turned [SQLITE_D
4aa60 4f 4e 45 5d 2c 20 6f 72 20 77 68 65 6e 20 74 68 ONE], or when th
4aa70 65 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f e .** applicatio
4aa80 6e 20 77 69 73 68 65 73 20 74 6f 20 61 62 61 6e n wishes to aban
4aa90 64 6f 6e 20 74 68 65 20 62 61 63 6b 75 70 20 6f don the backup o
4aaa0 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 peration, the ap
4aab0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f plication.** sho
4aac0 75 6c 64 20 64 65 73 74 72 6f 79 20 74 68 65 20 uld destroy the
4aad0 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
4aae0 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 by passing it t
4aaf0 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
4ab00 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a 20 5e 54 _finish()..** ^T
4ab10 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 he sqlite3_backu
4ab20 70 5f 66 69 6e 69 73 68 28 29 20 69 6e 74 65 72 p_finish() inter
4ab30 66 61 63 65 73 20 72 65 6c 65 61 73 65 73 20 61 faces releases a
4ab40 6c 6c 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 ll.** resources
4ab50 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
4ab60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 the [sqlite3_bac
4ab70 6b 75 70 5d 20 6f 62 6a 65 63 74 2e 20 0a 2a 2a kup] object. .**
4ab80 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 62 61 63 ^If sqlite3_bac
4ab90 6b 75 70 5f 73 74 65 70 28 29 20 68 61 73 20 6e kup_step() has n
4aba0 6f 74 20 79 65 74 20 72 65 74 75 72 6e 65 64 20 ot yet returned
4abb0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 74 [SQLITE_DONE], t
4abc0 68 65 6e 20 61 6e 79 0a 2a 2a 20 61 63 74 69 76 hen any.** activ
4abd0 65 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74 e write-transact
4abe0 69 6f 6e 20 6f 6e 20 74 68 65 20 64 65 73 74 69 ion on the desti
4abf0 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 nation database
4ac00 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a is rolled back..
4ac10 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
4ac20 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 20 69 backup] object i
4ac30 73 20 69 6e 76 61 6c 69 64 0a 2a 2a 20 61 6e 64 s invalid.** and
4ac40 20 6d 61 79 20 6e 6f 74 20 62 65 20 75 73 65 64 may not be used
4ac50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c following a cal
4ac60 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
4ac70 6b 75 70 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a kup_finish()..**
4ac80 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 .** ^The value r
4ac90 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
4aca0 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
4acb0 20 69 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 is [SQLITE_OK]
4acc0 69 66 20 6e 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 if no.** sqlite3
4acd0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 65 _backup_step() e
4ace0 72 72 6f 72 73 20 6f 63 63 75 72 72 65 64 2c 20 rrors occurred,
4acf0 72 65 67 61 72 64 6c 65 73 73 20 6f 72 20 77 68 regardless or wh
4ad00 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 ether or not.**
4ad10 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
4ad20 74 65 70 28 29 20 63 6f 6d 70 6c 65 74 65 64 2e tep() completed.
4ad30 0a 2a 2a 20 5e 49 66 20 61 6e 20 6f 75 74 2d 6f .** ^If an out-o
4ad40 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 f-memory conditi
4ad50 6f 6e 20 6f 72 20 49 4f 20 65 72 72 6f 72 20 6f on or IO error o
4ad60 63 63 75 72 72 65 64 20 64 75 72 69 6e 67 20 61 ccurred during a
4ad70 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 73 71 6c 69 ny prior.** sqli
4ad80 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
4ad90 29 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 ) call on the sa
4ada0 6d 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b me [sqlite3_back
4adb0 75 70 5d 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e up] object, then
4adc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
4add0 75 70 5f 66 69 6e 69 73 68 28 29 20 72 65 74 75 up_finish() retu
4ade0 72 6e 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f rns the correspo
4adf0 6e 64 69 6e 67 20 5b 65 72 72 6f 72 20 63 6f 64 nding [error cod
4ae00 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 72 65 74 e]..**.** ^A ret
4ae10 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 urn of [SQLITE_B
4ae20 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
4ae30 4c 4f 43 4b 45 44 5d 20 66 72 6f 6d 20 73 71 6c LOCKED] from sql
4ae40 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
4ae50 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 70 ().** is not a p
4ae60 65 72 6d 61 6e 65 6e 74 20 65 72 72 6f 72 20 61 ermanent error a
4ae70 6e 64 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 nd does not affe
4ae80 63 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ct the return va
4ae90 6c 75 65 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 lue of.** sqlite
4aea0 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
4aeb0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 )..**.** [[sqlit
4aec0 65 33 5f 62 61 63 6b 75 70 5f 5f 72 65 6d 61 69 e3_backup__remai
4aed0 6e 69 6e 67 28 29 5d 5d 20 5b 5b 73 71 6c 69 74 ning()]] [[sqlit
4aee0 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f e3_backup_pageco
4aef0 75 6e 74 28 29 5d 5d 0a 2a 2a 20 3c 62 3e 73 71 unt()]].** <b>sq
4af00 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d lite3_backup_rem
4af10 61 69 6e 69 6e 67 28 29 20 61 6e 64 20 73 71 6c aining() and sql
4af20 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 ite3_backup_page
4af30 63 6f 75 6e 74 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a count()</b>.**.*
4af40 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 * ^Each call to
4af50 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
4af60 74 65 70 28 29 20 73 65 74 73 20 74 77 6f 20 76 tep() sets two v
4af70 61 6c 75 65 73 20 69 6e 73 69 64 65 0a 2a 2a 20 alues inside.**
4af80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 the [sqlite3_bac
4af90 6b 75 70 5d 20 6f 62 6a 65 63 74 3a 20 74 68 65 kup] object: the
4afa0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
4afb0 20 73 74 69 6c 6c 20 74 6f 20 62 65 20 62 61 63 still to be bac
4afc0 6b 65 64 0a 2a 2a 20 75 70 20 61 6e 64 20 74 68 ked.** up and th
4afd0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
4afe0 66 20 70 61 67 65 73 20 69 6e 20 74 68 65 20 73 f pages in the s
4aff0 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 66 ource database f
4b000 69 6c 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ile..** The sqli
4b010 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 te3_backup_remai
4b020 6e 69 6e 67 28 29 20 61 6e 64 20 73 71 6c 69 74 ning() and sqlit
4b030 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f e3_backup_pageco
4b040 75 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 73 unt() interfaces
4b050 0a 2a 2a 20 72 65 74 72 69 65 76 65 20 74 68 65 .** retrieve the
4b060 73 65 20 74 77 6f 20 76 61 6c 75 65 73 2c 20 72 se two values, r
4b070 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
4b080 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 ** ^The values r
4b090 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
4b0a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 6f functions are o
4b0b0 6e 6c 79 20 75 70 64 61 74 65 64 20 62 79 0a 2a nly updated by.*
4b0c0 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 * sqlite3_backup
4b0d0 5f 73 74 65 70 28 29 2e 20 5e 49 66 20 74 68 65 _step(). ^If the
4b0e0 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 source database
4b0f0 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 75 72 is modified dur
4b100 69 6e 67 20 61 20 62 61 63 6b 75 70 0a 2a 2a 20 ing a backup.**
4b110 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 operation, then
4b120 74 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 6e the values are n
4b130 6f 74 20 75 70 64 61 74 65 64 20 74 6f 20 61 63 ot updated to ac
4b140 63 6f 75 6e 74 20 66 6f 72 20 61 6e 79 20 65 78 count for any ex
4b150 74 72 61 0a 2a 2a 20 70 61 67 65 73 20 74 68 61 tra.** pages tha
4b160 74 20 6e 65 65 64 20 74 6f 20 62 65 20 75 70 64 t need to be upd
4b170 61 74 65 64 20 6f 72 20 74 68 65 20 73 69 7a 65 ated or the size
4b180 20 6f 66 20 74 68 65 20 73 6f 75 72 63 65 20 64 of the source d
4b190 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 atabase file.**
4b1a0 63 68 61 6e 67 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 changing..**.**
4b1b0 3c 62 3e 43 6f 6e 63 75 72 72 65 6e 74 20 55 73 <b>Concurrent Us
4b1c0 61 67 65 20 6f 66 20 44 61 74 61 62 61 73 65 20 age of Database
4b1d0 48 61 6e 64 6c 65 73 3c 2f 62 3e 0a 2a 2a 0a 2a Handles</b>.**.*
4b1e0 2a 20 5e 54 68 65 20 73 6f 75 72 63 65 20 5b 64 * ^The source [d
4b1f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4b200 6f 6e 5d 20 6d 61 79 20 62 65 20 75 73 65 64 20 on] may be used
4b210 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
4b220 6f 6e 20 66 6f 72 20 6f 74 68 65 72 0a 2a 2a 20 on for other.**
4b230 70 75 72 70 6f 73 65 73 20 77 68 69 6c 65 20 61 purposes while a
4b240 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
4b250 6e 20 69 73 20 75 6e 64 65 72 77 61 79 20 6f 72 n is underway or
4b260 20 62 65 69 6e 67 20 69 6e 69 74 69 61 6c 69 7a being initializ
4b270 65 64 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 ed..** ^If SQLit
4b280 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 61 6e e is compiled an
4b290 64 20 63 6f 6e 66 69 67 75 72 65 64 20 74 6f 20 d configured to
4b2a0 73 75 70 70 6f 72 74 20 74 68 72 65 61 64 73 61 support threadsa
4b2b0 66 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 fe database.** c
4b2c0 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 74 68 65 6e onnections, then
4b2d0 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 the source data
4b2e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
4b2f0 6d 61 79 20 62 65 20 75 73 65 64 20 63 6f 6e 63 may be used conc
4b300 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 66 72 6f 6d urrently.** from
4b310 20 77 69 74 68 69 6e 20 6f 74 68 65 72 20 74 68 within other th
4b320 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 48 6f 77 reads..**.** How
4b330 65 76 65 72 2c 20 74 68 65 20 61 70 70 6c 69 63 ever, the applic
4b340 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 ation must guara
4b350 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 64 65 ntee that the de
4b360 73 74 69 6e 61 74 69 6f 6e 20 0a 2a 2a 20 5b 64 stination .** [d
4b370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4b380 6f 6e 5d 20 69 73 20 6e 6f 74 20 70 61 73 73 65 on] is not passe
4b390 64 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 41 d to any other A
4b3a0 50 49 20 28 62 79 20 61 6e 79 20 74 68 72 65 61 PI (by any threa
4b3b0 64 29 20 61 66 74 65 72 20 0a 2a 2a 20 73 71 6c d) after .** sql
4b3c0 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 ite3_backup_init
4b3d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 () is called and
4b3e0 20 62 65 66 6f 72 65 20 74 68 65 20 63 6f 72 72 before the corr
4b3f0 65 73 70 6f 6e 64 69 6e 67 20 63 61 6c 6c 20 74 esponding call t
4b400 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 o.** sqlite3_bac
4b410 6b 75 70 5f 66 69 6e 69 73 68 28 29 2e 20 20 53 kup_finish(). S
4b420 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 63 QLite does not c
4b430 75 72 72 65 6e 74 6c 79 20 63 68 65 63 6b 20 74 urrently check t
4b440 6f 20 73 65 65 0a 2a 2a 20 69 66 20 74 68 65 20 o see.** if the
4b450 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 63 6f application inco
4b460 72 72 65 63 74 6c 79 20 61 63 63 65 73 73 65 73 rrectly accesses
4b470 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e the destination
4b480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
4b490 63 74 69 6f 6e 5d 0a 2a 2a 20 61 6e 64 20 73 6f ction].** and so
4b4a0 20 6e 6f 20 65 72 72 6f 72 20 63 6f 64 65 20 69 no error code i
4b4b0 73 20 72 65 70 6f 72 74 65 64 2c 20 62 75 74 20 s reported, but
4b4c0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 6d the operations m
4b4d0 61 79 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a ay malfunction.*
4b4e0 2a 20 6e 65 76 65 72 74 68 65 6c 65 73 73 2e 20 * nevertheless.
4b4f0 20 55 73 65 20 6f 66 20 74 68 65 20 64 65 73 74 Use of the dest
4b500 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
4b510 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
4b520 65 20 61 0a 2a 2a 20 62 61 63 6b 75 70 20 69 73 e a.** backup is
4b530 20 69 6e 20 70 72 6f 67 72 65 73 73 20 6d 69 67 in progress mig
4b540 68 74 20 61 6c 73 6f 20 61 6c 73 6f 20 63 61 75 ht also also cau
4b550 73 65 20 61 20 6d 75 74 65 78 20 64 65 61 64 6c se a mutex deadl
4b560 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 72 75 ock..**.** If ru
4b570 6e 6e 69 6e 67 20 69 6e 20 5b 73 68 61 72 65 64 nning in [shared
4b580 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 74 68 cache mode], th
4b590 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
4b5a0 73 74 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 20 st.** guarantee
4b5b0 74 68 61 74 20 74 68 65 20 73 68 61 72 65 64 20 that the shared
4b5c0 63 61 63 68 65 20 75 73 65 64 20 62 79 20 74 68 cache used by th
4b5d0 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 e destination da
4b5e0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 tabase.** is not
4b5f0 20 61 63 63 65 73 73 65 64 20 77 68 69 6c 65 20 accessed while
4b600 74 68 65 20 62 61 63 6b 75 70 20 69 73 20 72 75 the backup is ru
4b610 6e 6e 69 6e 67 2e 20 49 6e 20 70 72 61 63 74 69 nning. In practi
4b620 63 65 20 74 68 69 73 20 6d 65 61 6e 73 0a 2a 2a ce this means.**
4b630 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 that the applic
4b640 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 ation must guara
4b650 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 64 69 ntee that the di
4b660 73 6b 20 66 69 6c 65 20 62 65 69 6e 67 20 0a 2a sk file being .*
4b670 2a 20 62 61 63 6b 65 64 20 75 70 20 74 6f 20 69 * backed up to i
4b680 73 20 6e 6f 74 20 61 63 63 65 73 73 65 64 20 62 s not accessed b
4b690 79 20 61 6e 79 20 63 6f 6e 6e 65 63 74 69 6f 6e y any connection
4b6a0 20 77 69 74 68 69 6e 20 74 68 65 20 70 72 6f 63 within the proc
4b6b0 65 73 73 2c 0a 2a 2a 20 6e 6f 74 20 6a 75 73 74 ess,.** not just
4b6c0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 63 6f the specific co
4b6d0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 77 61 nnection that wa
4b6e0 73 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 s passed to sqli
4b6f0 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 te3_backup_init(
4b700 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 )..**.** The [sq
4b710 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 lite3_backup] ob
4b720 6a 65 63 74 20 69 74 73 65 6c 66 20 69 73 20 70 ject itself is p
4b730 61 72 74 69 61 6c 6c 79 20 74 68 72 65 61 64 73 artially threads
4b740 61 66 65 2e 20 4d 75 6c 74 69 70 6c 65 20 0a 2a afe. Multiple .*
4b750 2a 20 74 68 72 65 61 64 73 20 6d 61 79 20 73 61 * threads may sa
4b760 66 65 6c 79 20 6d 61 6b 65 20 6d 75 6c 74 69 70 fely make multip
4b770 6c 65 20 63 6f 6e 63 75 72 72 65 6e 74 20 63 61 le concurrent ca
4b780 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 lls to sqlite3_b
4b790 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 0a 2a 2a ackup_step()..**
4b7a0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 73 71 However, the sq
4b7b0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d lite3_backup_rem
4b7c0 61 69 6e 69 6e 67 28 29 20 61 6e 64 20 73 71 6c aining() and sql
4b7d0 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 ite3_backup_page
4b7e0 63 6f 75 6e 74 28 29 0a 2a 2a 20 41 50 49 73 20 count().** APIs
4b7f0 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 are not strictly
4b800 20 73 70 65 61 6b 69 6e 67 20 74 68 72 65 61 64 speaking thread
4b810 73 61 66 65 2e 20 49 66 20 74 68 65 79 20 61 72 safe. If they ar
4b820 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 74 68 65 e invoked at the
4b830 0a 2a 2a 20 73 61 6d 65 20 74 69 6d 65 20 61 73 .** same time as
4b840 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
4b850 69 73 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 is invoking sqli
4b860 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
4b870 29 20 69 74 20 69 73 0a 2a 2a 20 70 6f 73 73 69 ) it is.** possi
4b880 62 6c 65 20 74 68 61 74 20 74 68 65 79 20 72 65 ble that they re
4b890 74 75 72 6e 20 69 6e 76 61 6c 69 64 20 76 61 6c turn invalid val
4b8a0 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ues..*/.SQLITE_A
4b8b0 50 49 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 PI sqlite3_backu
4b8c0 70 20 2a 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 p *sqlite3_backu
4b8d0 70 5f 69 6e 69 74 28 0a 20 20 73 71 6c 69 74 65 p_init(. sqlite
4b8e0 33 20 2a 70 44 65 73 74 2c 20 20 20 20 20 20 20 3 *pDest,
4b8f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4b900 20 2f 2a 20 44 65 73 74 69 6e 61 74 69 6f 6e 20 /* Destination
4b910 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 database handle
4b920 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
4b930 2a 7a 44 65 73 74 4e 61 6d 65 2c 20 20 20 20 20 *zDestName,
4b940 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
4b950 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
4b960 61 73 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 73 71 ase name */. sq
4b970 6c 69 74 65 33 20 2a 70 53 6f 75 72 63 65 2c 20 lite3 *pSource,
4b980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4b990 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 65 20 64 /* Source d
4b9a0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
4b9b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
4b9c0 7a 53 6f 75 72 63 65 4e 61 6d 65 20 20 20 20 20 zSourceName
4b9d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 6f /* So
4b9e0 75 72 63 65 20 64 61 74 61 62 61 73 65 20 6e 61 urce database na
4b9f0 6d 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f me */.);.SQLITE_
4ba00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
4ba10 62 61 63 6b 75 70 5f 73 74 65 70 28 73 71 6c 69 backup_step(sqli
4ba20 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 2c 20 69 te3_backup *p, i
4ba30 6e 74 20 6e 50 61 67 65 29 3b 0a 53 51 4c 49 54 nt nPage);.SQLIT
4ba40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
4ba50 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
4ba60 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a sqlite3_backup *
4ba70 70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 p);.SQLITE_API i
4ba80 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 nt sqlite3_backu
4ba90 70 5f 72 65 6d 61 69 6e 69 6e 67 28 73 71 6c 69 p_remaining(sqli
4baa0 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 29 3b 0a te3_backup *p);.
4bab0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
4bac0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 qlite3_backup_pa
4bad0 67 65 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f gecount(sqlite3_
4bae0 62 61 63 6b 75 70 20 2a 70 29 3b 0a 0a 2f 2a 0a backup *p);../*.
4baf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 6e 6c ** CAPI3REF: Unl
4bb00 6f 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e ock Notification
4bb10 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 72 75 6e .**.** ^When run
4bb20 6e 69 6e 67 20 69 6e 20 73 68 61 72 65 64 2d 63 ning in shared-c
4bb30 61 63 68 65 20 6d 6f 64 65 2c 20 61 20 64 61 74 ache mode, a dat
4bb40 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 abase operation
4bb50 6d 61 79 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a may fail with.**
4bb60 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b an [SQLITE_LOCK
4bb70 45 44 5d 20 65 72 72 6f 72 20 69 66 20 74 68 65 ED] error if the
4bb80 20 72 65 71 75 69 72 65 64 20 6c 6f 63 6b 73 20 required locks
4bb90 6f 6e 20 74 68 65 20 73 68 61 72 65 64 2d 63 61 on the shared-ca
4bba0 63 68 65 20 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 che or.** indivi
4bbb0 64 75 61 6c 20 74 61 62 6c 65 73 20 77 69 74 68 dual tables with
4bbc0 69 6e 20 74 68 65 20 73 68 61 72 65 64 2d 63 61 in the shared-ca
4bbd0 63 68 65 20 63 61 6e 6e 6f 74 20 62 65 20 6f 62 che cannot be ob
4bbe0 74 61 69 6e 65 64 2e 20 53 65 65 0a 2a 2a 20 5b tained. See.** [
4bbf0 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 SQLite Shared-Ca
4bc00 63 68 65 20 4d 6f 64 65 5d 20 66 6f 72 20 61 20 che Mode] for a
4bc10 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 73 description of s
4bc20 68 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b hared-cache lock
4bc30 69 6e 67 2e 20 0a 2a 2a 20 5e 54 68 69 73 20 41 ing. .** ^This A
4bc40 50 49 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 PI may be used t
4bc50 6f 20 72 65 67 69 73 74 65 72 20 61 20 63 61 6c o register a cal
4bc60 6c 62 61 63 6b 20 74 68 61 74 20 53 51 4c 69 74 lback that SQLit
4bc70 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 0a 2a e will invoke .*
4bc80 2a 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 6e 65 * when the conne
4bc90 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 ction currently
4bca0 68 6f 6c 64 69 6e 67 20 74 68 65 20 72 65 71 75 holding the requ
4bcb0 69 72 65 64 20 6c 6f 63 6b 20 72 65 6c 69 6e 71 ired lock relinq
4bcc0 75 69 73 68 65 73 20 69 74 2e 0a 2a 2a 20 5e 54 uishes it..** ^T
4bcd0 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 his API is only
4bce0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
4bcf0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
4bd00 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
4bd10 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
4bd20 5f 55 4e 4c 4f 43 4b 5f 4e 4f 54 49 46 59 5d 20 _UNLOCK_NOTIFY]
4bd30 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
4bd40 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a ymbol defined..*
4bd50 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 5b *.** See Also: [
4bd60 55 73 69 6e 67 20 74 68 65 20 53 51 4c 69 74 65 Using the SQLite
4bd70 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 66 69 63 61 Unlock Notifica
4bd80 74 69 6f 6e 20 46 65 61 74 75 72 65 5d 2e 0a 2a tion Feature]..*
4bd90 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 2d 63 61 63 *.** ^Shared-cac
4bda0 68 65 20 6c 6f 63 6b 73 20 61 72 65 20 72 65 6c he locks are rel
4bdb0 65 61 73 65 64 20 77 68 65 6e 20 61 20 64 61 74 eased when a dat
4bdc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4bdd0 20 63 6f 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 74 concludes.** it
4bde0 73 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 s current transa
4bdf0 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 20 62 79 ction, either by
4be00 20 63 6f 6d 6d 69 74 74 69 6e 67 20 69 74 20 6f committing it o
4be10 72 20 72 6f 6c 6c 69 6e 67 20 69 74 20 62 61 63 r rolling it bac
4be20 6b 2e 20 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 k. .**.** ^When
4be30 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 6b 6e a connection (kn
4be40 6f 77 6e 20 61 73 20 74 68 65 20 62 6c 6f 63 6b own as the block
4be50 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 20 66 ed connection) f
4be60 61 69 6c 73 20 74 6f 20 6f 62 74 61 69 6e 20 61 ails to obtain a
4be70 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 68 65 .** shared-cache
4be80 20 6c 6f 63 6b 20 61 6e 64 20 53 51 4c 49 54 45 lock and SQLITE
4be90 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 75 72 _LOCKED is retur
4bea0 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 ned to the calle
4beb0 72 2c 20 74 68 65 0a 2a 2a 20 69 64 65 6e 74 69 r, the.** identi
4bec0 74 79 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ty of the databa
4bed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 74 se connection (t
4bee0 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e he blocking conn
4bef0 65 63 74 69 6f 6e 29 20 74 68 61 74 0a 2a 2a 20 ection) that.**
4bf00 68 61 73 20 6c 6f 63 6b 65 64 20 74 68 65 20 72 has locked the r
4bf10 65 71 75 69 72 65 64 20 72 65 73 6f 75 72 63 65 equired resource
4bf20 20 69 73 20 73 74 6f 72 65 64 20 69 6e 74 65 72 is stored inter
4bf30 6e 61 6c 6c 79 2e 20 5e 41 66 74 65 72 20 61 6e nally. ^After an
4bf40 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e .** application
4bf50 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c receives an SQL
4bf60 49 54 45 5f 4c 4f 43 4b 45 44 20 65 72 72 6f 72 ITE_LOCKED error
4bf70 2c 20 69 74 20 6d 61 79 20 63 61 6c 6c 20 74 68 , it may call th
4bf80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c e.** sqlite3_unl
4bf90 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 6d 65 74 ock_notify() met
4bfa0 68 6f 64 20 77 69 74 68 20 74 68 65 20 62 6c 6f hod with the blo
4bfb0 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 cked connection
4bfc0 68 61 6e 64 6c 65 20 61 73 20 0a 2a 2a 20 74 68 handle as .** th
4bfd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
4bfe0 20 74 6f 20 72 65 67 69 73 74 65 72 20 66 6f 72 to register for
4bff0 20 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 a callback that
4c000 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
4c010 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 62 6c 6f .** when the blo
4c020 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
4c030 73 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 s current transa
4c040 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 ction is conclud
4c050 65 64 2e 20 5e 54 68 65 0a 2a 2a 20 63 61 6c 6c ed. ^The.** call
4c060 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
4c070 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
4c080 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 20 6f [sqlite3_step] o
4c090 72 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 r [sqlite3_close
4c0a0 5d 0a 2a 2a 20 63 61 6c 6c 20 74 68 61 74 20 63 ].** call that c
4c0b0 6f 6e 63 6c 75 64 65 73 20 74 68 65 20 62 6c 6f oncludes the blo
4c0c0 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
4c0d0 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 2a s transaction..*
4c0e0 2a 0a 2a 2a 20 5e 28 49 66 20 73 71 6c 69 74 65 *.** ^(If sqlite
4c0f0 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
4c100 29 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 20 61 ) is called in a
4c110 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 multi-threaded
4c120 61 70 70 6c 69 63 61 74 69 6f 6e 2c 0a 2a 2a 20 application,.**
4c130 74 68 65 72 65 20 69 73 20 61 20 63 68 61 6e 63 there is a chanc
4c140 65 20 74 68 61 74 20 74 68 65 20 62 6c 6f 63 6b e that the block
4c150 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ing connection w
4c160 69 6c 6c 20 68 61 76 65 20 61 6c 72 65 61 64 79 ill have already
4c170 0a 2a 2a 20 63 6f 6e 63 6c 75 64 65 64 20 69 74 .** concluded it
4c180 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 79 s transaction by
4c190 20 74 68 65 20 74 69 6d 65 20 73 71 6c 69 74 65 the time sqlite
4c1a0 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
4c1b0 29 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a ) is invoked..**
4c1c0 20 49 66 20 74 68 69 73 20 68 61 70 70 65 6e 73 If this happens
4c1d0 2c 20 74 68 65 6e 20 74 68 65 20 73 70 65 63 69 , then the speci
4c1e0 66 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 69 73 fied callback is
4c1f0 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 64 69 61 invoked immedia
4c200 74 65 6c 79 2c 0a 2a 2a 20 66 72 6f 6d 20 77 69 tely,.** from wi
4c210 74 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f thin the call to
4c220 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f sqlite3_unlock_
4c230 6e 6f 74 69 66 79 28 29 2e 29 5e 0a 2a 2a 0a 2a notify().)^.**.*
4c240 2a 20 5e 49 66 20 74 68 65 20 62 6c 6f 63 6b 65 * ^If the blocke
4c250 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 d connection is
4c260 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 6f 62 attempting to ob
4c270 74 61 69 6e 20 61 20 77 72 69 74 65 2d 6c 6f 63 tain a write-loc
4c280 6b 20 6f 6e 20 61 0a 2a 2a 20 73 68 61 72 65 64 k on a.** shared
4c290 2d 63 61 63 68 65 20 74 61 62 6c 65 2c 20 61 6e -cache table, an
4c2a0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 d more than one
4c2b0 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e other connection
4c2c0 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 73 currently holds
4c2d0 0a 2a 2a 20 61 20 72 65 61 64 2d 6c 6f 63 6b 20 .** a read-lock
4c2e0 6f 6e 20 74 68 65 20 73 61 6d 65 20 74 61 62 6c on the same tabl
4c2f0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 e, then SQLite a
4c300 72 62 69 74 72 61 72 69 6c 79 20 73 65 6c 65 63 rbitrarily selec
4c310 74 73 20 6f 6e 65 20 6f 66 20 0a 2a 2a 20 74 68 ts one of .** th
4c320 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 e other connecti
4c330 6f 6e 73 20 74 6f 20 75 73 65 20 61 73 20 74 68 ons to use as th
4c340 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 e blocking conne
4c350 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ction..**.** ^(T
4c360 68 65 72 65 20 6d 61 79 20 62 65 20 61 74 20 6d here may be at m
4c370 6f 73 74 20 6f 6e 65 20 75 6e 6c 6f 63 6b 2d 6e ost one unlock-n
4c380 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 72 otify callback r
4c390 65 67 69 73 74 65 72 65 64 20 62 79 20 61 20 0a egistered by a .
4c3a0 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 ** blocked conne
4c3b0 63 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 ction. If sqlite
4c3c0 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
4c3d0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e ) is called when
4c3e0 20 74 68 65 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 the.** blocked
4c3f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6c 72 65 61 connection alrea
4c400 64 79 20 68 61 73 20 61 20 72 65 67 69 73 74 65 dy has a registe
4c410 72 65 64 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 red unlock-notif
4c420 79 20 63 61 6c 6c 62 61 63 6b 2c 0a 2a 2a 20 74 y callback,.** t
4c430 68 65 6e 20 74 68 65 20 6e 65 77 20 63 61 6c 6c hen the new call
4c440 62 61 63 6b 20 72 65 70 6c 61 63 65 73 20 74 68 back replaces th
4c450 65 20 6f 6c 64 2e 29 5e 20 5e 49 66 20 73 71 6c e old.)^ ^If sql
4c460 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
4c470 66 79 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 fy() is.** calle
4c480 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f d with a NULL po
4c490 69 6e 74 65 72 20 61 73 20 69 74 73 20 73 65 63 inter as its sec
4c4a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 ond argument, th
4c4b0 65 6e 20 61 6e 79 20 65 78 69 73 74 69 6e 67 0a en any existing.
4c4c0 2a 2a 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 ** unlock-notify
4c4d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e callback is can
4c4e0 63 65 6c 65 64 2e 20 5e 54 68 65 20 62 6c 6f 63 celed. ^The bloc
4c4f0 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ked connections
4c500 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 .** unlock-notif
4c510 79 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 61 y callback may a
4c520 6c 73 6f 20 62 65 20 63 61 6e 63 65 6c 65 64 20 lso be canceled
4c530 62 79 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 62 by closing the b
4c540 6c 6f 63 6b 65 64 0a 2a 2a 20 63 6f 6e 6e 65 63 locked.** connec
4c550 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 tion using [sqli
4c560 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a te3_close()]..**
4c570 0a 2a 2a 20 54 68 65 20 75 6e 6c 6f 63 6b 2d 6e .** The unlock-n
4c580 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 otify callback i
4c590 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e s not reentrant.
4c5a0 20 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 If an applicati
4c5b0 6f 6e 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 61 6e on invokes.** an
4c5c0 79 20 73 71 6c 69 74 65 33 5f 78 78 78 20 41 50 y sqlite3_xxx AP
4c5d0 49 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d I functions from
4c5e0 20 77 69 74 68 69 6e 20 61 6e 20 75 6e 6c 6f 63 within an unloc
4c5f0 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 k-notify callbac
4c600 6b 2c 20 61 0a 2a 2a 20 63 72 61 73 68 20 6f 72 k, a.** crash or
4c610 20 64 65 61 64 6c 6f 63 6b 20 6d 61 79 20 62 65 deadlock may be
4c620 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a the result..**.
4c630 2a 2a 20 5e 55 6e 6c 65 73 73 20 64 65 61 64 6c ** ^Unless deadl
4c640 6f 63 6b 20 69 73 20 64 65 74 65 63 74 65 64 20 ock is detected
4c650 28 73 65 65 20 62 65 6c 6f 77 29 2c 20 73 71 6c (see below), sql
4c660 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
4c670 66 79 28 29 20 61 6c 77 61 79 73 0a 2a 2a 20 72 fy() always.** r
4c680 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b eturns SQLITE_OK
4c690 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 43 61 6c 6c 62 ..**.** <b>Callb
4c6a0 61 63 6b 20 49 6e 76 6f 63 61 74 69 6f 6e 20 44 ack Invocation D
4c6b0 65 74 61 69 6c 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a etails</b>.**.**
4c6c0 20 57 68 65 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d When an unlock-
4c6d0 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
4c6e0 69 73 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 is registered, t
4c6f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 he application p
4c700 72 6f 76 69 64 65 73 20 61 20 0a 2a 2a 20 73 69 rovides a .** si
4c710 6e 67 6c 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 ngle void* point
4c720 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 er that is passe
4c730 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 d to the callbac
4c740 6b 20 77 68 65 6e 20 69 74 20 69 73 20 69 6e 76 k when it is inv
4c750 6f 6b 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 oked..** However
4c760 2c 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 , the signature
4c770 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 of the callback
4c780 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 function allows
4c790 53 51 4c 69 74 65 20 74 6f 20 70 61 73 73 0a 2a SQLite to pass.*
4c7a0 2a 20 69 74 20 61 6e 20 61 72 72 61 79 20 6f 66 * it an array of
4c7b0 20 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 20 70 void* context p
4c7c0 6f 69 6e 74 65 72 73 2e 20 54 68 65 20 66 69 72 ointers. The fir
4c7d0 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 st argument pass
4c7e0 65 64 20 74 6f 0a 2a 2a 20 61 6e 20 75 6e 6c 6f ed to.** an unlo
4c7f0 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 ck-notify callba
4c800 63 6b 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ck is a pointer
4c810 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 76 to an array of v
4c820 6f 69 64 2a 20 70 6f 69 6e 74 65 72 73 2c 0a 2a oid* pointers,.*
4c830 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 * and the second
4c840 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
4c850 66 20 65 6e 74 72 69 65 73 20 69 6e 20 74 68 65 f entries in the
4c860 20 61 72 72 61 79 2e 0a 2a 2a 0a 2a 2a 20 57 68 array..**.** Wh
4c870 65 6e 20 61 20 62 6c 6f 63 6b 69 6e 67 20 63 6f en a blocking co
4c880 6e 6e 65 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 nnections transa
4c890 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 ction is conclud
4c8a0 65 64 2c 20 74 68 65 72 65 20 6d 61 79 20 62 65 ed, there may be
4c8b0 0a 2a 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e .** more than on
4c8c0 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
4c8d0 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 72 65 tion that has re
4c8e0 67 69 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 gistered for an
4c8f0 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a unlock-notify.**
4c900 20 63 61 6c 6c 62 61 63 6b 2e 20 5e 49 66 20 74 callback. ^If t
4c910 77 6f 20 6f 72 20 6d 6f 72 65 20 73 75 63 68 20 wo or more such
4c920 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 blocked connecti
4c930 6f 6e 73 20 68 61 76 65 20 73 70 65 63 69 66 69 ons have specifi
4c940 65 64 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 63 ed the.** same c
4c950 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
4c960 2c 20 74 68 65 6e 20 69 6e 73 74 65 61 64 20 6f , then instead o
4c970 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 f invoking the c
4c980 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
4c990 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d .** multiple tim
4c9a0 65 73 2c 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 es, it is invoke
4c9b0 64 20 6f 6e 63 65 20 77 69 74 68 20 74 68 65 20 d once with the
4c9c0 73 65 74 20 6f 66 20 76 6f 69 64 2a 20 63 6f 6e set of void* con
4c9d0 74 65 78 74 20 70 6f 69 6e 74 65 72 73 0a 2a 2a text pointers.**
4c9e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
4c9f0 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
4ca00 74 69 6f 6e 73 20 62 75 6e 64 6c 65 64 20 74 6f tions bundled to
4ca10 67 65 74 68 65 72 20 69 6e 74 6f 20 61 6e 20 61 gether into an a
4ca20 72 72 61 79 2e 0a 2a 2a 20 54 68 69 73 20 67 69 rray..** This gi
4ca30 76 65 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 ves the applicat
4ca40 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 ion an opportuni
4ca50 74 79 20 74 6f 20 70 72 69 6f 72 69 74 69 7a 65 ty to prioritize
4ca60 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 0a 2a 2a any actions .**
4ca70 20 72 65 6c 61 74 65 64 20 74 6f 20 74 68 65 20 related to the
4ca80 73 65 74 20 6f 66 20 75 6e 62 6c 6f 63 6b 65 64 set of unblocked
4ca90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
4caa0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e tions..**.** <b>
4cab0 44 65 61 64 6c 6f 63 6b 20 44 65 74 65 63 74 69 Deadlock Detecti
4cac0 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 41 73 73 on</b>.**.** Ass
4cad0 75 6d 69 6e 67 20 74 68 61 74 20 61 66 74 65 72 uming that after
4cae0 20 72 65 67 69 73 74 65 72 69 6e 67 20 66 6f 72 registering for
4caf0 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 an unlock-notif
4cb00 79 20 63 61 6c 6c 62 61 63 6b 20 61 20 0a 2a 2a y callback a .**
4cb10 20 64 61 74 61 62 61 73 65 20 77 61 69 74 73 20 database waits
4cb20 66 6f 72 20 74 68 65 20 63 61 6c 6c 62 61 63 6b for the callback
4cb30 20 74 6f 20 62 65 20 69 73 73 75 65 64 20 62 65 to be issued be
4cb40 66 6f 72 65 20 74 61 6b 69 6e 67 20 61 6e 79 20 fore taking any
4cb50 66 75 72 74 68 65 72 0a 2a 2a 20 61 63 74 69 6f further.** actio
4cb60 6e 20 28 61 20 72 65 61 73 6f 6e 61 62 6c 65 20 n (a reasonable
4cb70 61 73 73 75 6d 70 74 69 6f 6e 29 2c 20 74 68 65 assumption), the
4cb80 6e 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 n using this API
4cb90 20 6d 61 79 20 63 61 75 73 65 20 74 68 65 0a 2a may cause the.*
4cba0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f * application to
4cbb0 20 64 65 61 64 6c 6f 63 6b 2e 20 46 6f 72 20 65 deadlock. For e
4cbc0 78 61 6d 70 6c 65 2c 20 69 66 20 63 6f 6e 6e 65 xample, if conne
4cbd0 63 74 69 6f 6e 20 58 20 69 73 20 77 61 69 74 69 ction X is waiti
4cbe0 6e 67 20 66 6f 72 0a 2a 2a 20 63 6f 6e 6e 65 63 ng for.** connec
4cbf0 74 69 6f 6e 20 59 27 73 20 74 72 61 6e 73 61 63 tion Y's transac
4cc00 74 69 6f 6e 20 74 6f 20 62 65 20 63 6f 6e 63 6c tion to be concl
4cc10 75 64 65 64 2c 20 61 6e 64 20 73 69 6d 69 6c 61 uded, and simila
4cc20 72 6c 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a rly connection.*
4cc30 2a 20 59 20 69 73 20 77 61 69 74 69 6e 67 20 6f * Y is waiting o
4cc40 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 58 27 73 n connection X's
4cc50 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
4cc60 65 6e 20 6e 65 69 74 68 65 72 20 63 6f 6e 6e 65 en neither conne
4cc70 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 70 72 ction.** will pr
4cc80 6f 63 65 65 64 20 61 6e 64 20 74 68 65 20 73 79 oceed and the sy
4cc90 73 74 65 6d 20 6d 61 79 20 72 65 6d 61 69 6e 20 stem may remain
4cca0 64 65 61 64 6c 6f 63 6b 65 64 20 69 6e 64 65 66 deadlocked indef
4ccb0 69 6e 69 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 initely..**.** T
4ccc0 6f 20 61 76 6f 69 64 20 74 68 69 73 20 73 63 65 o avoid this sce
4ccd0 6e 61 72 69 6f 2c 20 74 68 65 20 73 71 6c 69 74 nario, the sqlit
4cce0 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 e3_unlock_notify
4ccf0 28 29 20 70 65 72 66 6f 72 6d 73 20 64 65 61 64 () performs dead
4cd00 6c 6f 63 6b 0a 2a 2a 20 64 65 74 65 63 74 69 6f lock.** detectio
4cd10 6e 2e 20 5e 49 66 20 61 20 67 69 76 65 6e 20 63 n. ^If a given c
4cd20 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 all to sqlite3_u
4cd30 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 77 nlock_notify() w
4cd40 6f 75 6c 64 20 70 75 74 20 74 68 65 0a 2a 2a 20 ould put the.**
4cd50 73 79 73 74 65 6d 20 69 6e 20 61 20 64 65 61 64 system in a dead
4cd60 6c 6f 63 6b 65 64 20 73 74 61 74 65 2c 20 74 68 locked state, th
4cd70 65 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 en SQLITE_LOCKED
4cd80 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
4cd90 20 6e 6f 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d 6e 6f no.** unlock-no
4cda0 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 tify callback is
4cdb0 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65 registered. The
4cdc0 20 73 79 73 74 65 6d 20 69 73 20 73 61 69 64 20 system is said
4cdd0 74 6f 20 62 65 20 69 6e 0a 2a 2a 20 61 20 64 65 to be in.** a de
4cde0 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 65 20 69 adlocked state i
4cdf0 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 41 20 68 f connection A h
4ce00 61 73 20 72 65 67 69 73 74 65 72 65 64 20 66 6f as registered fo
4ce10 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 r an unlock-noti
4ce20 66 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f fy.** callback o
4ce30 6e 20 74 68 65 20 63 6f 6e 63 6c 75 73 69 6f 6e n the conclusion
4ce40 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 42 of connection B
4ce50 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 's transaction,
4ce60 61 6e 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a and connection.*
4ce70 2a 20 42 20 68 61 73 20 69 74 73 65 6c 66 20 72 * B has itself r
4ce80 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 61 6e egistered for an
4ce90 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
4cea0 61 6c 6c 62 61 63 6b 20 77 68 65 6e 20 63 6f 6e allback when con
4ceb0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 41 27 73 20 74 nection.** A's t
4cec0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f ransaction is co
4ced0 6e 63 6c 75 64 65 64 2e 20 5e 49 6e 64 69 72 65 ncluded. ^Indire
4cee0 63 74 20 64 65 61 64 6c 6f 63 6b 20 69 73 20 61 ct deadlock is a
4cef0 6c 73 6f 20 64 65 74 65 63 74 65 64 2c 20 73 6f lso detected, so
4cf00 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 69 .** the system i
4cf10 73 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 65 s also considere
4cf20 64 20 74 6f 20 62 65 20 64 65 61 64 6c 6f 63 6b d to be deadlock
4cf30 65 64 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e ed if connection
4cf40 20 42 20 68 61 73 0a 2a 2a 20 72 65 67 69 73 74 B has.** regist
4cf50 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f ered for an unlo
4cf60 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 ck-notify callba
4cf70 63 6b 20 6f 6e 20 74 68 65 20 63 6f 6e 63 6c 75 ck on the conclu
4cf80 73 69 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 sion of connecti
4cf90 6f 6e 0a 2a 2a 20 43 27 73 20 74 72 61 6e 73 61 on.** C's transa
4cfa0 63 74 69 6f 6e 2c 20 77 68 65 72 65 20 63 6f 6e ction, where con
4cfb0 6e 65 63 74 69 6f 6e 20 43 20 69 73 20 77 61 69 nection C is wai
4cfc0 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 ting on connecti
4cfd0 6f 6e 20 41 2e 20 5e 41 6e 79 0a 2a 2a 20 6e 75 on A. ^Any.** nu
4cfe0 6d 62 65 72 20 6f 66 20 6c 65 76 65 6c 73 20 6f mber of levels o
4cff0 66 20 69 6e 64 69 72 65 63 74 69 6f 6e 20 61 72 f indirection ar
4d000 65 20 61 6c 6c 6f 77 65 64 2e 0a 2a 2a 0a 2a 2a e allowed..**.**
4d010 20 3c 62 3e 54 68 65 20 22 44 52 4f 50 20 54 41 <b>The "DROP TA
4d020 42 4c 45 22 20 45 78 63 65 70 74 69 6f 6e 3c 2f BLE" Exception</
4d030 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 b>.**.** When a
4d040 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
4d050 5f 73 74 65 70 28 29 5d 20 72 65 74 75 72 6e 73 _step()] returns
4d060 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 2c 20 SQLITE_LOCKED,
4d070 69 74 20 69 73 20 61 6c 6d 6f 73 74 20 0a 2a 2a it is almost .**
4d080 20 61 6c 77 61 79 73 20 61 70 70 72 6f 70 72 69 always appropri
4d090 61 74 65 20 74 6f 20 63 61 6c 6c 20 73 71 6c 69 ate to call sqli
4d0a0 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 te3_unlock_notif
4d0b0 79 28 29 2e 20 54 68 65 72 65 20 69 73 20 68 6f y(). There is ho
4d0c0 77 65 76 65 72 2c 0a 2a 2a 20 6f 6e 65 20 65 78 wever,.** one ex
4d0d0 63 65 70 74 69 6f 6e 2e 20 57 68 65 6e 20 65 78 ception. When ex
4d0e0 65 63 75 74 69 6e 67 20 61 20 22 44 52 4f 50 20 ecuting a "DROP
4d0f0 54 41 42 4c 45 22 20 6f 72 20 22 44 52 4f 50 20 TABLE" or "DROP
4d100 49 4e 44 45 58 22 20 73 74 61 74 65 6d 65 6e 74 INDEX" statement
4d110 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 63 68 65 63 ,.** SQLite chec
4d120 6b 73 20 69 66 20 74 68 65 72 65 20 61 72 65 20 ks if there are
4d130 61 6e 79 20 63 75 72 72 65 6e 74 6c 79 20 65 78 any currently ex
4d140 65 63 75 74 69 6e 67 20 53 45 4c 45 43 54 20 73 ecuting SELECT s
4d150 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
4d160 74 20 62 65 6c 6f 6e 67 20 74 6f 20 74 68 65 20 t belong to the
4d170 73 61 6d 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e same connection.
4d180 20 49 66 20 74 68 65 72 65 20 61 72 65 2c 20 53 If there are, S
4d190 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 73 0a QLITE_LOCKED is.
4d1a0 2a 2a 20 72 65 74 75 72 6e 65 64 2e 20 49 6e 20 ** returned. In
4d1b0 74 68 69 73 20 63 61 73 65 20 74 68 65 72 65 20 this case there
4d1c0 69 73 20 6e 6f 20 22 62 6c 6f 63 6b 69 6e 67 20 is no "blocking
4d1d0 63 6f 6e 6e 65 63 74 69 6f 6e 22 2c 20 73 6f 20 connection", so
4d1e0 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 invoking.** sqli
4d1f0 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 te3_unlock_notif
4d200 79 28 29 20 72 65 73 75 6c 74 73 20 69 6e 20 74 y() results in t
4d210 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 he unlock-notify
4d220 20 63 61 6c 6c 62 61 63 6b 20 62 65 69 6e 67 0a callback being.
4d230 2a 2a 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 64 ** invoked immed
4d240 69 61 74 65 6c 79 2e 20 49 66 20 74 68 65 20 61 iately. If the a
4d250 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 65 6e 20 pplication then
4d260 72 65 2d 61 74 74 65 6d 70 74 73 20 74 68 65 20 re-attempts the
4d270 22 44 52 4f 50 20 54 41 42 4c 45 22 0a 2a 2a 20 "DROP TABLE".**
4d280 6f 72 20 22 44 52 4f 50 20 49 4e 44 45 58 22 20 or "DROP INDEX"
4d290 71 75 65 72 79 2c 20 61 6e 20 69 6e 66 69 6e 69 query, an infini
4d2a0 74 65 20 6c 6f 6f 70 20 6d 69 67 68 74 20 62 65 te loop might be
4d2b0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a the result..**.
4d2c0 2a 2a 20 4f 6e 65 20 77 61 79 20 61 72 6f 75 6e ** One way aroun
4d2d0 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 69 d this problem i
4d2e0 73 20 74 6f 20 63 68 65 63 6b 20 74 68 65 20 65 s to check the e
4d2f0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
4d300 64 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 de returned.** b
4d310 79 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 74 65 y an sqlite3_ste
4d320 70 28 29 20 63 61 6c 6c 2e 20 5e 28 49 66 20 74 p() call. ^(If t
4d330 68 65 72 65 20 69 73 20 61 20 62 6c 6f 63 6b 69 here is a blocki
4d340 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 ng connection, t
4d350 68 65 6e 20 74 68 65 0a 2a 2a 20 65 78 74 65 6e hen the.** exten
4d360 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 20 69 ded error code i
4d370 73 20 73 65 74 20 74 6f 20 53 51 4c 49 54 45 5f s set to SQLITE_
4d380 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 LOCKED_SHAREDCAC
4d390 48 45 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 69 HE. Otherwise, i
4d3a0 6e 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c n.** the special
4d3b0 20 22 44 52 4f 50 20 54 41 42 4c 45 2f 49 4e 44 "DROP TABLE/IND
4d3c0 45 58 22 20 63 61 73 65 2c 20 74 68 65 20 65 78 EX" case, the ex
4d3d0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
4d3e0 65 20 69 73 20 6a 75 73 74 20 0a 2a 2a 20 53 51 e is just .** SQ
4d3f0 4c 49 54 45 5f 4c 4f 43 4b 45 44 2e 29 5e 0a 2a LITE_LOCKED.)^.*
4d400 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
4d410 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f sqlite3_unlock_
4d420 6e 6f 74 69 66 79 28 0a 20 20 73 71 6c 69 74 65 notify(. sqlite
4d430 33 20 2a 70 42 6c 6f 63 6b 65 64 2c 20 20 20 20 3 *pBlocked,
4d440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4d450 20 20 20 20 20 20 2f 2a 20 57 61 69 74 69 6e 67 /* Waiting
4d460 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 connection */.
4d470 20 76 6f 69 64 20 28 2a 78 4e 6f 74 69 66 79 29 void (*xNotify)
4d480 28 76 6f 69 64 20 2a 2a 61 70 41 72 67 2c 20 69 (void **apArg, i
4d490 6e 74 20 6e 41 72 67 29 2c 20 20 20 20 2f 2a 20 nt nArg), /*
4d4a0 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f Callback functio
4d4b0 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 2a 2f 0a 20 n to invoke */.
4d4c0 20 76 6f 69 64 20 2a 70 4e 6f 74 69 66 79 41 72 void *pNotifyAr
4d4d0 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
4d4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
4d4f0 41 72 67 75 6d 65 6e 74 20 74 6f 20 70 61 73 73 Argument to pass
4d500 20 74 6f 20 78 4e 6f 74 69 66 79 20 2a 2f 0a 29 to xNotify */.)
4d510 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
4d520 45 46 3a 20 53 74 72 69 6e 67 20 43 6f 6d 70 61 EF: String Compa
4d530 72 69 73 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rison.**.** ^The
4d540 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 [sqlite3_strnic
4d550 6d 70 28 29 5d 20 41 50 49 20 61 6c 6c 6f 77 73 mp()] API allows
4d560 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e applications an
4d570 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 6f 0a d extensions to.
4d580 2a 2a 20 63 6f 6d 70 61 72 65 20 74 68 65 20 63 ** compare the c
4d590 6f 6e 74 65 6e 74 73 20 6f 66 20 74 77 6f 20 62 ontents of two b
4d5a0 75 66 66 65 72 73 20 63 6f 6e 74 61 69 6e 69 6e uffers containin
4d5b0 67 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 g UTF-8 strings
4d5c0 69 6e 20 61 0a 2a 2a 20 63 61 73 65 2d 69 6e 64 in a.** case-ind
4d5d0 65 70 65 6e 64 65 6e 74 20 66 61 73 68 69 6f 6e ependent fashion
4d5e0 2c 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 , using the same
4d5f0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 63 definition of c
4d600 61 73 65 20 69 6e 64 65 70 65 6e 64 65 6e 63 65 ase independence
4d610 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 .** that SQLite
4d620 20 75 73 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79 uses internally
4d630 20 77 68 65 6e 20 63 6f 6d 70 61 72 69 6e 67 20 when comparing
4d640 69 64 65 6e 74 69 66 69 65 72 73 2e 0a 2a 2f 0a identifiers..*/.
4d650 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
4d660 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 qlite3_strnicmp(
4d670 63 6f 6e 73 74 20 63 68 61 72 20 2a 2c 20 63 6f const char *, co
4d680 6e 73 74 20 63 68 61 72 20 2a 2c 20 69 6e 74 29 nst char *, int)
4d690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
4d6a0 46 3a 20 45 72 72 6f 72 20 4c 6f 67 67 69 6e 67 F: Error Logging
4d6b0 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a Interface.**.**
4d6c0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c ^The [sqlite3_l
4d6d0 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 og()] interface
4d6e0 77 72 69 74 65 73 20 61 20 6d 65 73 73 61 67 65 writes a message
4d6f0 20 69 6e 74 6f 20 74 68 65 20 65 72 72 6f 72 20 into the error
4d700 6c 6f 67 0a 2a 2a 20 65 73 74 61 62 6c 69 73 68 log.** establish
4d710 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ed by the [SQLIT
4d720 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 20 6f 70 E_CONFIG_LOG] op
4d730 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 tion to [sqlite3
4d740 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e _config()]..** ^
4d750 49 66 20 6c 6f 67 67 69 6e 67 20 69 73 20 65 6e If logging is en
4d760 61 62 6c 65 64 2c 20 74 68 65 20 7a 46 6f 72 6d abled, the zForm
4d770 61 74 20 73 74 72 69 6e 67 20 61 6e 64 20 73 75 at string and su
4d780 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
4d790 74 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 77 ts are.** used w
4d7a0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ith [sqlite3_snp
4d7b0 72 69 6e 74 66 28 29 5d 20 74 6f 20 67 65 6e 65 rintf()] to gene
4d7c0 72 61 74 65 20 74 68 65 20 66 69 6e 61 6c 20 6f rate the final o
4d7d0 75 74 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a utput string..**
4d7e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
4d7f0 6c 6f 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 log() interface
4d800 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
4d810 75 73 65 20 62 79 20 65 78 74 65 6e 73 69 6f 6e use by extension
4d820 73 20 73 75 63 68 20 61 73 0a 2a 2a 20 76 69 72 s such as.** vir
4d830 74 75 61 6c 20 74 61 62 6c 65 73 2c 20 63 6f 6c tual tables, col
4d840 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 lating functions
4d850 2c 20 61 6e 64 20 53 51 4c 20 66 75 6e 63 74 69 , and SQL functi
4d860 6f 6e 73 2e 20 20 57 68 69 6c 65 20 74 68 65 72 ons. While ther
4d870 65 20 69 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 e is.** nothing
4d880 74 6f 20 70 72 65 76 65 6e 74 20 61 6e 20 61 70 to prevent an ap
4d890 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 20 63 plication from c
4d8a0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c alling sqlite3_l
4d8b0 6f 67 28 29 2c 20 64 6f 69 6e 67 20 73 6f 0a 2a og(), doing so.*
4d8c0 2a 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 * is considered
4d8d0 62 61 64 20 66 6f 72 6d 2e 0a 2a 2a 0a 2a 2a 20 bad form..**.**
4d8e0 54 68 65 20 7a 46 6f 72 6d 61 74 20 73 74 72 69 The zFormat stri
4d8f0 6e 67 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 4e ng must not be N
4d900 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 ULL..**.** To av
4d910 6f 69 64 20 64 65 61 64 6c 6f 63 6b 73 20 61 6e oid deadlocks an
4d920 64 20 6f 74 68 65 72 20 74 68 72 65 61 64 69 6e d other threadin
4d930 67 20 70 72 6f 62 6c 65 6d 73 2c 20 74 68 65 20 g problems, the
4d940 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 72 6f sqlite3_log() ro
4d950 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 6e 6f utine.** will no
4d960 74 20 75 73 65 20 64 79 6e 61 6d 69 63 61 6c 6c t use dynamicall
4d970 79 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f y allocated memo
4d980 72 79 2e 20 20 54 68 65 20 6c 6f 67 20 6d 65 73 ry. The log mes
4d990 73 61 67 65 20 69 73 20 73 74 6f 72 65 64 20 69 sage is stored i
4d9a0 6e 0a 2a 2a 20 61 20 66 69 78 65 64 2d 6c 65 6e n.** a fixed-len
4d9b0 67 74 68 20 62 75 66 66 65 72 20 6f 6e 20 74 68 gth buffer on th
4d9c0 65 20 73 74 61 63 6b 2e 20 20 49 66 20 74 68 65 e stack. If the
4d9d0 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 69 73 20 log message is
4d9e0 6c 6f 6e 67 65 72 20 74 68 61 6e 0a 2a 2a 20 61 longer than.** a
4d9f0 20 66 65 77 20 68 75 6e 64 72 65 64 20 63 68 61 few hundred cha
4da00 72 61 63 74 65 72 73 2c 20 69 74 20 77 69 6c 6c racters, it will
4da10 20 62 65 20 74 72 75 6e 63 61 74 65 64 20 74 6f be truncated to
4da20 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 the length of t
4da30 68 65 0a 2a 2a 20 62 75 66 66 65 72 2e 0a 2a 2f he.** buffer..*/
4da40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
4da50 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 69 6e 74 sqlite3_log(int
4da60 20 69 45 72 72 43 6f 64 65 2c 20 63 6f 6e 73 74 iErrCode, const
4da70 20 63 68 61 72 20 2a 7a 46 6f 72 6d 61 74 2c 20 char *zFormat,
4da80 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
4da90 49 33 52 45 46 3a 20 57 72 69 74 65 2d 41 68 65 I3REF: Write-Ahe
4daa0 61 64 20 4c 6f 67 20 43 6f 6d 6d 69 74 20 48 6f ad Log Commit Ho
4dab0 6f 6b 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 ok.**.** ^The [s
4dac0 71 6c 69 74 65 33 5f 77 61 6c 5f 68 6f 6f 6b 28 qlite3_wal_hook(
4dad0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 )] function is u
4dae0 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 sed to register
4daf0 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 0a a callback that.
4db00 2a 2a 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b ** will be invok
4db10 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 64 ed each time a d
4db20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4db30 6f 6e 20 63 6f 6d 6d 69 74 73 20 64 61 74 61 20 on commits data
4db40 74 6f 20 61 0a 2a 2a 20 5b 77 72 69 74 65 2d 61 to a.** [write-a
4db50 68 65 61 64 20 6c 6f 67 5d 20 28 69 2e 65 2e 20 head log] (i.e.
4db60 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 whenever a trans
4db70 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 action is commit
4db80 74 65 64 20 69 6e 0a 2a 2a 20 5b 6a 6f 75 72 6e ted in.** [journ
4db90 61 6c 5f 6d 6f 64 65 20 7c 20 6a 6f 75 72 6e 61 al_mode | journa
4dba0 6c 5f 6d 6f 64 65 3d 57 41 4c 20 6d 6f 64 65 5d l_mode=WAL mode]
4dbb0 29 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 ). .**.** ^The c
4dbc0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
4dbd0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 ed by SQLite aft
4dbe0 65 72 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 61 er the commit ha
4dbf0 73 20 74 61 6b 65 6e 20 70 6c 61 63 65 20 61 6e s taken place an
4dc00 64 20 0a 2a 2a 20 74 68 65 20 61 73 73 6f 63 69 d .** the associ
4dc10 61 74 65 64 20 77 72 69 74 65 2d 6c 6f 63 6b 20 ated write-lock
4dc20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 on the database
4dc30 72 65 6c 65 61 73 65 64 2c 20 73 6f 20 74 68 65 released, so the
4dc40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
4dc50 0a 2a 2a 20 6d 61 79 20 72 65 61 64 2c 20 77 72 .** may read, wr
4dc60 69 74 65 20 6f 72 20 5b 63 68 65 63 6b 70 6f 69 ite or [checkpoi
4dc70 6e 74 5d 20 74 68 65 20 64 61 74 61 62 61 73 65 nt] the database
4dc80 20 61 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a as required..**
4dc90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
4dca0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 arameter passed
4dcb0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
4dcc0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 69 74 function when it
4dcd0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 69 is invoked.** i
4dce0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
4dcf0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
4dd00 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 passed to sqlite
4dd10 33 5f 77 61 6c 5f 68 6f 6f 6b 28 29 20 77 68 65 3_wal_hook() whe
4dd20 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 69 6e 67 n.** registering
4dd30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 5e the callback. ^
4dd40 54 68 65 20 73 65 63 6f 6e 64 20 69 73 20 61 20 The second is a
4dd50 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
4dd60 62 61 73 65 20 68 61 6e 64 6c 65 2e 0a 2a 2a 20 base handle..**
4dd70 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d ^The third param
4dd80 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 eter is the name
4dd90 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
4dda0 20 74 68 61 74 20 77 61 73 20 77 72 69 74 74 65 that was writte
4ddb0 6e 20 74 6f 20 2d 0a 2a 2a 20 65 69 74 68 65 72 n to -.** either
4ddc0 20 22 6d 61 69 6e 22 20 6f 72 20 74 68 65 20 6e "main" or the n
4ddd0 61 6d 65 20 6f 66 20 61 6e 20 5b 41 54 54 41 43 ame of an [ATTAC
4dde0 48 5d 2d 65 64 20 64 61 74 61 62 61 73 65 2e 20 H]-ed database.
4ddf0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 ^The fourth para
4de00 6d 65 74 65 72 0a 2a 2a 20 69 73 20 74 68 65 20 meter.** is the
4de10 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
4de20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 74 68 65 currently in the
4de30 20 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 write-ahead log
4de40 20 66 69 6c 65 2c 0a 2a 2a 20 69 6e 63 6c 75 64 file,.** includ
4de50 69 6e 67 20 74 68 6f 73 65 20 74 68 61 74 20 77 ing those that w
4de60 65 72 65 20 6a 75 73 74 20 63 6f 6d 6d 69 74 74 ere just committ
4de70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ed..**.** The ca
4de80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
4de90 73 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 should normally
4dea0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
4deb0 4b 5d 2e 20 20 5e 49 66 20 61 6e 20 65 72 72 6f K]. ^If an erro
4dec0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 72 65 74 r.** code is ret
4ded0 75 72 6e 65 64 2c 20 74 68 61 74 20 65 72 72 6f urned, that erro
4dee0 72 20 77 69 6c 6c 20 70 72 6f 70 61 67 61 74 65 r will propagate
4def0 20 62 61 63 6b 20 75 70 20 74 68 72 6f 75 67 68 back up through
4df00 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 63 the.** SQLite c
4df10 6f 64 65 20 62 61 73 65 20 74 6f 20 63 61 75 73 ode base to caus
4df20 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 e the statement
4df30 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 that provoked th
4df40 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f e callback.** to
4df50 20 72 65 70 6f 72 74 20 61 6e 20 65 72 72 6f 72 report an error
4df60 2c 20 74 68 6f 75 67 68 20 74 68 65 20 63 6f 6d , though the com
4df70 6d 69 74 20 77 69 6c 6c 20 68 61 76 65 20 73 74 mit will have st
4df80 69 6c 6c 20 6f 63 63 75 72 72 65 64 2e 20 49 66 ill occurred. If
4df90 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b the.** callback
4dfa0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
4dfb0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 _ROW] or [SQLITE
4dfc0 5f 44 4f 4e 45 5d 2c 20 6f 72 20 69 66 20 69 74 _DONE], or if it
4dfd0 20 72 65 74 75 72 6e 73 20 61 20 76 61 6c 75 65 returns a value
4dfe0 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
4dff0 74 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 t correspond to
4e000 61 6e 79 20 76 61 6c 69 64 20 53 51 4c 69 74 65 any valid SQLite
4e010 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 error code, the
4e020 20 72 65 73 75 6c 74 73 0a 2a 2a 20 61 72 65 20 results.** are
4e030 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
4e040 20 41 20 73 69 6e 67 6c 65 20 64 61 74 61 62 61 A single databa
4e050 73 65 20 68 61 6e 64 6c 65 20 6d 61 79 20 68 61 se handle may ha
4e060 76 65 20 61 74 20 6d 6f 73 74 20 61 20 73 69 6e ve at most a sin
4e070 67 6c 65 20 77 72 69 74 65 2d 61 68 65 61 64 20 gle write-ahead
4e080 6c 6f 67 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a log callback .**
4e090 20 72 65 67 69 73 74 65 72 65 64 20 61 74 20 6f registered at o
4e0a0 6e 65 20 74 69 6d 65 2e 20 5e 43 61 6c 6c 69 6e ne time. ^Callin
4e0b0 67 20 5b 73 71 6c 69 74 65 33 5f 77 61 6c 5f 68 g [sqlite3_wal_h
4e0c0 6f 6f 6b 28 29 5d 20 72 65 70 6c 61 63 65 73 20 ook()] replaces
4e0d0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c any.** previousl
4e0e0 79 20 72 65 67 69 73 74 65 72 65 64 20 77 72 69 y registered wri
4e0f0 74 65 2d 61 68 65 61 64 20 6c 6f 67 20 63 61 6c te-ahead log cal
4e100 6c 62 61 63 6b 2e 20 5e 4e 6f 74 65 20 74 68 61 lback. ^Note tha
4e110 74 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 t the.** [sqlite
4e120 33 5f 77 61 6c 5f 61 75 74 6f 63 68 65 63 6b 70 3_wal_autocheckp
4e130 6f 69 6e 74 28 29 5d 20 69 6e 74 65 72 66 61 63 oint()] interfac
4e140 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 77 61 e and the.** [wa
4e150 6c 5f 61 75 74 6f 63 68 65 63 6b 70 6f 69 6e 74 l_autocheckpoint
4e160 20 70 72 61 67 6d 61 5d 20 62 6f 74 68 20 69 6e pragma] both in
4e170 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 77 61 voke [sqlite3_wa
4e180 6c 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 77 69 l_hook()] and wi
4e190 6c 6c 0a 2a 2a 20 74 68 6f 73 65 20 6f 76 65 72 ll.** those over
4e1a0 77 72 69 74 65 20 61 6e 79 20 70 72 69 6f 72 20 write any prior
4e1b0 5b 73 71 6c 69 74 65 33 5f 77 61 6c 5f 68 6f 6f [sqlite3_wal_hoo
4e1c0 6b 28 29 5d 20 73 65 74 74 69 6e 67 73 2e 0a 2a k()] settings..*
4e1d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
4e1e0 64 20 2a 73 71 6c 69 74 65 33 5f 77 61 6c 5f 68 d *sqlite3_wal_h
4e1f0 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ook(. sqlite3*,
4e200 20 0a 20 20 69 6e 74 28 2a 29 28 76 6f 69 64 20 . int(*)(void
4e210 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 *,sqlite3*,const
4e220 20 63 68 61 72 2a 2c 69 6e 74 29 2c 0a 20 20 76 char*,int),. v
4e230 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 oid*.);../*.** C
4e240 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
4e250 72 65 20 61 6e 20 61 75 74 6f 2d 63 68 65 63 6b re an auto-check
4e260 70 6f 69 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 point.**.** ^The
4e270 20 5b 73 71 6c 69 74 65 33 5f 77 61 6c 5f 61 75 [sqlite3_wal_au
4e280 74 6f 63 68 65 63 6b 70 6f 69 6e 74 28 44 2c 4e tocheckpoint(D,N
4e290 29 5d 20 69 73 20 61 20 77 72 61 70 70 65 72 20 )] is a wrapper
4e2a0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 around.** [sqlit
4e2b0 65 33 5f 77 61 6c 5f 68 6f 6f 6b 28 29 5d 20 74 e3_wal_hook()] t
4e2c0 68 61 74 20 63 61 75 73 65 73 20 61 6e 79 20 64 hat causes any d
4e2d0 61 74 61 62 61 73 65 20 6f 6e 20 5b 64 61 74 61 atabase on [data
4e2e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
4e2f0 20 44 0a 2a 2a 20 74 6f 20 61 75 74 6f 6d 61 74 D.** to automat
4e300 69 63 61 6c 6c 79 20 5b 63 68 65 63 6b 70 6f 69 ically [checkpoi
4e310 6e 74 5d 0a 2a 2a 20 61 66 74 65 72 20 63 6f 6d nt].** after com
4e320 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 mitting a transa
4e330 63 74 69 6f 6e 20 69 66 20 74 68 65 72 65 20 61 ction if there a
4e340 72 65 20 4e 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 re N or.** more
4e350 66 72 61 6d 65 73 20 69 6e 20 74 68 65 20 5b 77 frames in the [w
4e360 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 20 rite-ahead log]
4e370 66 69 6c 65 2e 20 20 5e 50 61 73 73 69 6e 67 20 file. ^Passing
4e380 7a 65 72 6f 20 6f 72 20 0a 2a 2a 20 61 20 6e 65 zero or .** a ne
4e390 67 61 74 69 76 65 20 76 61 6c 75 65 20 61 73 20 gative value as
4e3a0 74 68 65 20 6e 46 72 61 6d 65 20 70 61 72 61 6d the nFrame param
4e3b0 65 74 65 72 20 64 69 73 61 62 6c 65 73 20 61 75 eter disables au
4e3c0 74 6f 6d 61 74 69 63 0a 2a 2a 20 63 68 65 63 6b tomatic.** check
4e3d0 70 6f 69 6e 74 73 20 65 6e 74 69 72 65 6c 79 2e points entirely.
4e3e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c .**.** ^The call
4e3f0 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 20 back registered
4e400 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e by this function
4e410 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 replaces any ex
4e420 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 0a isting callback.
4e430 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 75 73 ** registered us
4e440 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 77 61 6c ing [sqlite3_wal
4e450 5f 68 6f 6f 6b 28 29 5d 2e 20 20 5e 4c 69 6b 65 _hook()]. ^Like
4e460 77 69 73 65 2c 20 72 65 67 69 73 74 65 72 69 6e wise, registerin
4e470 67 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 g a callback.**
4e480 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 77 using [sqlite3_w
4e490 61 6c 5f 68 6f 6f 6b 28 29 5d 20 64 69 73 61 62 al_hook()] disab
4e4a0 6c 65 73 20 74 68 65 20 61 75 74 6f 6d 61 74 69 les the automati
4e4b0 63 20 63 68 65 63 6b 70 6f 69 6e 74 20 6d 65 63 c checkpoint mec
4e4c0 68 61 6e 69 73 6d 0a 2a 2a 20 63 6f 6e 66 69 67 hanism.** config
4e4d0 75 72 65 64 20 62 79 20 74 68 69 73 20 66 75 6e ured by this fun
4e4e0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ction..**.** ^Th
4e4f0 65 20 5b 77 61 6c 5f 61 75 74 6f 63 68 65 63 6b e [wal_autocheck
4e500 70 6f 69 6e 74 20 70 72 61 67 6d 61 5d 20 63 61 point pragma] ca
4e510 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6e 76 n be used to inv
4e520 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 oke this interfa
4e530 63 65 0a 2a 2a 20 66 72 6f 6d 20 53 51 4c 2e 0a ce.** from SQL..
4e540 2a 2a 0a 2a 2a 20 5e 45 76 65 72 79 20 6e 65 77 **.** ^Every new
4e550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
4e560 63 74 69 6f 6e 5d 20 64 65 66 61 75 6c 74 73 20 ction] defaults
4e570 74 6f 20 68 61 76 69 6e 67 20 74 68 65 20 61 75 to having the au
4e580 74 6f 2d 63 68 65 63 6b 70 6f 69 6e 74 0a 2a 2a to-checkpoint.**
4e590 20 65 6e 61 62 6c 65 64 20 77 69 74 68 20 61 20 enabled with a
4e5a0 74 68 72 65 73 68 6f 6c 64 20 6f 66 20 31 30 30 threshold of 100
4e5b0 30 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 46 0 or [SQLITE_DEF
4e5c0 41 55 4c 54 5f 57 41 4c 5f 41 55 54 4f 43 48 45 AULT_WAL_AUTOCHE
4e5d0 43 4b 50 4f 49 4e 54 5d 0a 2a 2a 20 70 61 67 65 CKPOINT].** page
4e5e0 73 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 s. The use of t
4e5f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a his interface.**
4e600 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61 is only necessa
4e610 72 79 20 69 66 20 74 68 65 20 64 65 66 61 75 6c ry if the defaul
4e620 74 20 73 65 74 74 69 6e 67 20 69 73 20 66 6f 75 t setting is fou
4e630 6e 64 20 74 6f 20 62 65 20 73 75 62 6f 70 74 69 nd to be subopti
4e640 6d 61 6c 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 mal.** for a par
4e650 74 69 63 75 6c 61 72 20 61 70 70 6c 69 63 61 74 ticular applicat
4e660 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ion..*/.SQLITE_A
4e670 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 77 PI int sqlite3_w
4e680 61 6c 5f 61 75 74 6f 63 68 65 63 6b 70 6f 69 6e al_autocheckpoin
4e690 74 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 t(sqlite3 *db, i
4e6a0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt N);../*.** CA
4e6b0 50 49 33 52 45 46 3a 20 43 68 65 63 6b 70 6f 69 PI3REF: Checkpoi
4e6c0 6e 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a nt a database.**
4e6d0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
4e6e0 33 5f 77 61 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 3_wal_checkpoint
4e6f0 28 44 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 (D,X)] interface
4e700 20 63 61 75 73 65 73 20 64 61 74 61 62 61 73 65 causes database
4e710 20 6e 61 6d 65 64 20 58 0a 2a 2a 20 6f 6e 20 5b named X.** on [
4e720 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
4e730 69 6f 6e 5d 20 44 20 74 6f 20 62 65 20 5b 63 68 ion] D to be [ch
4e740 65 63 6b 70 6f 69 6e 74 65 64 5d 2e 20 20 5e 49 eckpointed]. ^I
4e750 66 20 58 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 f X is NULL or a
4e760 6e 0a 2a 2a 20 65 6d 70 74 79 20 73 74 72 69 6e n.** empty strin
4e770 67 2c 20 74 68 65 6e 20 61 20 63 68 65 63 6b 70 g, then a checkp
4e780 6f 69 6e 74 20 69 73 20 72 75 6e 20 6f 6e 20 61 oint is run on a
4e790 6c 6c 20 64 61 74 61 62 61 73 65 73 20 6f 66 0a ll databases of.
4e7a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e ** connection D.
4e7b0 20 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 ^If the databa
4e7c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 se connection D
4e7d0 69 73 20 6e 6f 74 20 69 6e 0a 2a 2a 20 5b 57 41 is not in.** [WA
4e7e0 4c 20 7c 20 77 72 69 74 65 2d 61 68 65 61 64 20 L | write-ahead
4e7f0 6c 6f 67 20 6d 6f 64 65 5d 20 74 68 65 6e 20 74 log mode] then t
4e800 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
4e810 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
4e820 70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 77 p..**.** ^The [w
4e830 61 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 20 70 72 al_checkpoint pr
4e840 61 67 6d 61 5d 20 63 61 6e 20 62 65 20 75 73 65 agma] can be use
4e850 64 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 69 73 d to invoke this
4e860 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 66 72 interface.** fr
4e870 6f 6d 20 53 51 4c 2e 20 20 5e 54 68 65 20 5b 73 om SQL. ^The [s
4e880 71 6c 69 74 65 33 5f 77 61 6c 5f 61 75 74 6f 63 qlite3_wal_autoc
4e890 68 65 63 6b 70 6f 69 6e 74 28 29 5d 20 69 6e 74 heckpoint()] int
4e8a0 65 72 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a erface and the.*
4e8b0 2a 20 5b 77 61 6c 5f 61 75 74 6f 63 68 65 63 6b * [wal_autocheck
4e8c0 70 6f 69 6e 74 20 70 72 61 67 6d 61 5d 20 63 61 point pragma] ca
4e8d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 61 75 n be used to cau
4e8e0 73 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 se this interfac
4e8f0 65 20 74 6f 20 62 65 0a 2a 2a 20 72 75 6e 20 77 e to be.** run w
4e900 68 65 6e 65 76 65 72 20 74 68 65 20 57 41 4c 20 henever the WAL
4e910 72 65 61 63 68 65 73 20 61 20 63 65 72 74 61 69 reaches a certai
4e920 6e 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 n size threshold
4e930 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
4e940 3a 20 5b 73 71 6c 69 74 65 33 5f 77 61 6c 5f 63 : [sqlite3_wal_c
4e950 68 65 63 6b 70 6f 69 6e 74 5f 76 32 28 29 5d 0a heckpoint_v2()].
4e960 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
4e970 74 20 73 71 6c 69 74 65 33 5f 77 61 6c 5f 63 68 t sqlite3_wal_ch
4e980 65 63 6b 70 6f 69 6e 74 28 73 71 6c 69 74 65 33 eckpoint(sqlite3
4e990 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 *db, const char
4e9a0 20 2a 7a 44 62 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *zDb);../*.** C
4e9b0 41 50 49 33 52 45 46 3a 20 43 68 65 63 6b 70 6f API3REF: Checkpo
4e9c0 69 6e 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a int a database.*
4e9d0 2a 0a 2a 2a 20 52 75 6e 20 61 20 63 68 65 63 6b *.** Run a check
4e9e0 70 6f 69 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 point operation
4e9f0 6f 6e 20 57 41 4c 20 64 61 74 61 62 61 73 65 20 on WAL database
4ea00 7a 44 62 20 61 74 74 61 63 68 65 64 20 74 6f 20 zDb attached to
4ea10 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 68 61 6e database .** han
4ea20 64 6c 65 20 64 62 2e 20 54 68 65 20 73 70 65 63 dle db. The spec
4ea30 69 66 69 63 20 6f 70 65 72 61 74 69 6f 6e 20 69 ific operation i
4ea40 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 s determined by
4ea50 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
4ea60 20 0a 2a 2a 20 65 4d 6f 64 65 20 70 61 72 61 6d .** eMode param
4ea70 65 74 65 72 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e eter:.**.** <dl>
4ea80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
4ea90 48 45 43 4b 50 4f 49 4e 54 5f 50 41 53 53 49 56 HECKPOINT_PASSIV
4eaa0 45 3c 64 64 3e 0a 2a 2a 20 20 20 43 68 65 63 6b E<dd>.** Check
4eab0 70 6f 69 6e 74 20 61 73 20 6d 61 6e 79 20 66 72 point as many fr
4eac0 61 6d 65 73 20 61 73 20 70 6f 73 73 69 62 6c 65 ames as possible
4ead0 20 77 69 74 68 6f 75 74 20 77 61 69 74 69 6e 67 without waiting
4eae0 20 66 6f 72 20 61 6e 79 20 64 61 74 61 62 61 73 for any databas
4eaf0 65 20 0a 2a 2a 20 20 20 72 65 61 64 65 72 73 20 e .** readers
4eb00 6f 72 20 77 72 69 74 65 72 73 20 74 6f 20 66 69 or writers to fi
4eb10 6e 69 73 68 2e 20 53 79 6e 63 20 74 68 65 20 64 nish. Sync the d
4eb20 62 20 66 69 6c 65 20 69 66 20 61 6c 6c 20 66 72 b file if all fr
4eb30 61 6d 65 73 20 69 6e 20 74 68 65 20 6c 6f 67 0a ames in the log.
4eb40 2a 2a 20 20 20 61 72 65 20 63 68 65 63 6b 70 6f ** are checkpo
4eb50 69 6e 74 65 64 2e 20 54 68 69 73 20 6d 6f 64 65 inted. This mode
4eb60 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
4eb70 63 61 6c 6c 69 6e 67 20 0a 2a 2a 20 20 20 73 71 calling .** sq
4eb80 6c 69 74 65 33 5f 77 61 6c 5f 63 68 65 63 6b 70 lite3_wal_checkp
4eb90 6f 69 6e 74 28 29 2e 20 54 68 65 20 62 75 73 79 oint(). The busy
4eba0 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 -handler callbac
4ebb0 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b k is never invok
4ebc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 ed..**.** <dt>SQ
4ebd0 4c 49 54 45 5f 43 48 45 43 4b 50 4f 49 4e 54 5f LITE_CHECKPOINT_
4ebe0 46 55 4c 4c 3c 64 64 3e 0a 2a 2a 20 20 20 54 68 FULL<dd>.** Th
4ebf0 69 73 20 6d 6f 64 65 20 62 6c 6f 63 6b 73 20 28 is mode blocks (
4ec00 63 61 6c 6c 73 20 74 68 65 20 62 75 73 79 2d 68 calls the busy-h
4ec10 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 29 andler callback)
4ec20 20 75 6e 74 69 6c 20 74 68 65 72 65 20 69 73 20 until there is
4ec30 6e 6f 0a 2a 2a 20 20 20 64 61 74 61 62 61 73 65 no.** database
4ec40 20 77 72 69 74 65 72 20 61 6e 64 20 61 6c 6c 20 writer and all
4ec50 72 65 61 64 65 72 73 20 61 72 65 20 72 65 61 64 readers are read
4ec60 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 ing from the mos
4ec70 74 20 72 65 63 65 6e 74 20 64 61 74 61 62 61 73 t recent databas
4ec80 65 0a 2a 2a 20 20 20 73 6e 61 70 73 68 6f 74 2e e.** snapshot.
4ec90 20 49 74 20 74 68 65 6e 20 63 68 65 63 6b 70 6f It then checkpo
4eca0 69 6e 74 73 20 61 6c 6c 20 66 72 61 6d 65 73 20 ints all frames
4ecb0 69 6e 20 74 68 65 20 6c 6f 67 20 66 69 6c 65 20 in the log file
4ecc0 61 6e 64 20 73 79 6e 63 73 20 74 68 65 0a 2a 2a and syncs the.**
4ecd0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 database file
4ece0 2e 20 54 68 69 73 20 63 61 6c 6c 20 62 6c 6f 63 . This call bloc
4ecf0 6b 73 20 64 61 74 61 62 61 73 65 20 77 72 69 74 ks database writ
4ed00 65 72 73 20 77 68 69 6c 65 20 69 74 20 69 73 20 ers while it is
4ed10 72 75 6e 6e 69 6e 67 2c 0a 2a 2a 20 20 20 62 75 running,.** bu
4ed20 74 20 6e 6f 74 20 64 61 74 61 62 61 73 65 20 72 t not database r
4ed30 65 61 64 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 3c 64 eaders..**.** <d
4ed40 74 3e 53 51 4c 49 54 45 5f 43 48 45 43 4b 50 4f t>SQLITE_CHECKPO
4ed50 49 4e 54 5f 52 45 53 54 41 52 54 3c 64 64 3e 0a INT_RESTART<dd>.
4ed60 2a 2a 20 20 20 54 68 69 73 20 6d 6f 64 65 20 77 ** This mode w
4ed70 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 77 61 orks the same wa
4ed80 79 20 61 73 20 53 51 4c 49 54 45 5f 43 48 45 43 y as SQLITE_CHEC
4ed90 4b 50 4f 49 4e 54 5f 46 55 4c 4c 2c 20 65 78 63 KPOINT_FULL, exc
4eda0 65 70 74 20 61 66 74 65 72 20 0a 2a 2a 20 20 20 ept after .**
4edb0 63 68 65 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 checkpointing th
4edc0 65 20 6c 6f 67 20 66 69 6c 65 20 69 74 20 62 6c e log file it bl
4edd0 6f 63 6b 73 20 28 63 61 6c 6c 73 20 74 68 65 20 ocks (calls the
4ede0 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c busy-handler cal
4edf0 6c 62 61 63 6b 29 0a 2a 2a 20 20 20 75 6e 74 69 lback).** unti
4ee00 6c 20 61 6c 6c 20 72 65 61 64 65 72 73 20 61 72 l all readers ar
4ee10 65 20 72 65 61 64 69 6e 67 20 66 72 6f 6d 20 74 e reading from t
4ee20 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
4ee30 20 6f 6e 6c 79 2e 20 54 68 69 73 20 65 6e 73 75 only. This ensu
4ee40 72 65 73 20 0a 2a 2a 20 20 20 74 68 61 74 20 74 res .** that t
4ee50 68 65 20 6e 65 78 74 20 63 6c 69 65 6e 74 20 74 he next client t
4ee60 6f 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 64 o write to the d
4ee70 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 atabase file res
4ee80 74 61 72 74 73 20 74 68 65 20 6c 6f 67 20 66 69 tarts the log fi
4ee90 6c 65 20 0a 2a 2a 20 20 20 66 72 6f 6d 20 74 68 le .** from th
4eea0 65 20 62 65 67 69 6e 6e 69 6e 67 2e 20 54 68 69 e beginning. Thi
4eeb0 73 20 63 61 6c 6c 20 62 6c 6f 63 6b 73 20 64 61 s call blocks da
4eec0 74 61 62 61 73 65 20 77 72 69 74 65 72 73 20 77 tabase writers w
4eed0 68 69 6c 65 20 69 74 20 69 73 20 72 75 6e 6e 69 hile it is runni
4eee0 6e 67 2c 0a 2a 2a 20 20 20 62 75 74 20 6e 6f 74 ng,.** but not
4eef0 20 64 61 74 61 62 61 73 65 20 72 65 61 64 65 72 database reader
4ef00 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a s..** </dl>.**.*
4ef10 2a 20 49 66 20 70 6e 4c 6f 67 20 69 73 20 6e 6f * If pnLog is no
4ef20 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 6e t NULL, then *pn
4ef30 4c 6f 67 20 69 73 20 73 65 74 20 74 6f 20 74 68 Log is set to th
4ef40 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
4ef50 66 20 66 72 61 6d 65 73 20 69 6e 0a 2a 2a 20 74 f frames in.** t
4ef60 68 65 20 6c 6f 67 20 66 69 6c 65 20 62 65 66 6f he log file befo
4ef70 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 20 49 66 re returning. If
4ef80 20 70 6e 43 6b 70 74 20 69 73 20 6e 6f 74 20 4e pnCkpt is not N
4ef90 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 6e 43 6b 70 ULL, then *pnCkp
4efa0 74 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 74 t is set to.** t
4efb0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 he total number
4efc0 6f 66 20 63 68 65 63 6b 70 6f 69 6e 74 65 64 20 of checkpointed
4efd0 66 72 61 6d 65 73 20 28 69 6e 63 6c 75 64 69 6e frames (includin
4efe0 67 20 61 6e 79 20 74 68 61 74 20 77 65 72 65 20 g any that were
4eff0 61 6c 72 65 61 64 79 0a 2a 2a 20 63 68 65 63 6b already.** check
4f000 70 6f 69 6e 74 65 64 20 77 68 65 6e 20 74 68 69 pointed when thi
4f010 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 s function is ca
4f020 6c 6c 65 64 29 2e 20 2a 70 6e 4c 6f 67 20 61 6e lled). *pnLog an
4f030 64 20 2a 70 6e 43 6b 70 74 20 6d 61 79 20 62 65 d *pnCkpt may be
4f040 0a 2a 2a 20 70 6f 70 75 6c 61 74 65 64 20 65 76 .** populated ev
4f050 65 6e 20 69 66 20 73 71 6c 69 74 65 33 5f 77 61 en if sqlite3_wa
4f060 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 5f 76 32 28 l_checkpoint_v2(
4f070 29 20 72 65 74 75 72 6e 73 20 6f 74 68 65 72 20 ) returns other
4f080 74 68 61 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a than SQLITE_OK..
4f090 2a 2a 20 49 66 20 6e 6f 20 76 61 6c 75 65 73 20 ** If no values
4f0a0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62 65 are available be
4f0b0 63 61 75 73 65 20 6f 66 20 61 6e 20 65 72 72 6f cause of an erro
4f0c0 72 2c 20 74 68 65 79 20 61 72 65 20 62 6f 74 68 r, they are both
4f0d0 20 73 65 74 20 74 6f 20 2d 31 0a 2a 2a 20 62 65 set to -1.** be
4f0e0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 74 fore returning t
4f0f0 6f 20 63 6f 6d 6d 75 6e 69 63 61 74 65 20 74 68 o communicate th
4f100 69 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 is to the caller
4f110 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 61 6c 6c ..**.** All call
4f120 73 20 6f 62 74 61 69 6e 20 61 6e 20 65 78 63 6c s obtain an excl
4f130 75 73 69 76 65 20 22 63 68 65 63 6b 70 6f 69 6e usive "checkpoin
4f140 74 22 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 t" lock on the d
4f150 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 atabase file. If
4f160 0a 2a 2a 20 61 6e 79 20 6f 74 68 65 72 20 70 72 .** any other pr
4f170 6f 63 65 73 73 20 69 73 20 72 75 6e 6e 69 6e 67 ocess is running
4f180 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 6f 70 a checkpoint op
4f190 65 72 61 74 69 6f 6e 20 61 74 20 74 68 65 20 73 eration at the s
4f1a0 61 6d 65 20 74 69 6d 65 2c 20 74 68 65 20 0a 2a ame time, the .*
4f1b0 2a 20 6c 6f 63 6b 20 63 61 6e 6e 6f 74 20 62 65 * lock cannot be
4f1c0 20 6f 62 74 61 69 6e 65 64 20 61 6e 64 20 53 51 obtained and SQ
4f1d0 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72 65 74 LITE_BUSY is ret
4f1e0 75 72 6e 65 64 2e 20 45 76 65 6e 20 69 66 20 74 urned. Even if t
4f1f0 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 62 75 here is a .** bu
4f200 73 79 2d 68 61 6e 64 6c 65 72 20 63 6f 6e 66 69 sy-handler confi
4f210 67 75 72 65 64 2c 20 69 74 20 77 69 6c 6c 20 6e gured, it will n
4f220 6f 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 69 6e ot be invoked in
4f230 20 74 68 69 73 20 63 61 73 65 2e 0a 2a 2a 0a 2a this case..**.*
4f240 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 43 48 45 * The SQLITE_CHE
4f250 43 4b 50 4f 49 4e 54 5f 46 55 4c 4c 20 61 6e 64 CKPOINT_FULL and
4f260 20 52 45 53 54 41 52 54 20 6d 6f 64 65 73 20 61 RESTART modes a
4f270 6c 73 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 65 lso obtain the e
4f280 78 63 6c 75 73 69 76 65 20 0a 2a 2a 20 22 77 72 xclusive .** "wr
4f290 69 74 65 72 22 20 6c 6f 63 6b 20 6f 6e 20 74 68 iter" lock on th
4f2a0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e e database file.
4f2b0 20 49 66 20 74 68 65 20 77 72 69 74 65 72 20 6c If the writer l
4f2c0 6f 63 6b 20 63 61 6e 6e 6f 74 20 62 65 20 6f 62 ock cannot be ob
4f2d0 74 61 69 6e 65 64 0a 2a 2a 20 69 6d 6d 65 64 69 tained.** immedi
4f2e0 61 74 65 6c 79 2c 20 61 6e 64 20 61 20 62 75 73 ately, and a bus
4f2f0 79 2d 68 61 6e 64 6c 65 72 20 69 73 20 63 6f 6e y-handler is con
4f300 66 69 67 75 72 65 64 2c 20 69 74 20 69 73 20 69 figured, it is i
4f310 6e 76 6f 6b 65 64 20 61 6e 64 20 74 68 65 20 77 nvoked and the w
4f320 72 69 74 65 72 0a 2a 2a 20 6c 6f 63 6b 20 72 65 riter.** lock re
4f330 74 72 69 65 64 20 75 6e 74 69 6c 20 65 69 74 68 tried until eith
4f340 65 72 20 74 68 65 20 62 75 73 79 2d 68 61 6e 64 er the busy-hand
4f350 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 6f 72 ler returns 0 or
4f360 20 74 68 65 20 6c 6f 63 6b 20 69 73 0a 2a 2a 20 the lock is.**
4f370 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 62 74 successfully obt
4f380 61 69 6e 65 64 2e 20 54 68 65 20 62 75 73 79 2d ained. The busy-
4f390 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 handler is also
4f3a0 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 77 61 invoked while wa
4f3b0 69 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 64 61 74 iting for.** dat
4f3c0 61 62 61 73 65 20 72 65 61 64 65 72 73 20 61 73 abase readers as
4f3d0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 described above
4f3e0 2e 20 49 66 20 74 68 65 20 62 75 73 79 2d 68 61 . If the busy-ha
4f3f0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 ndler returns 0
4f400 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 77 72 before.** the wr
4f410 69 74 65 72 20 6c 6f 63 6b 20 69 73 20 6f 62 74 iter lock is obt
4f420 61 69 6e 65 64 20 6f 72 20 77 68 69 6c 65 20 77 ained or while w
4f430 61 69 74 69 6e 67 20 66 6f 72 20 64 61 74 61 62 aiting for datab
4f440 61 73 65 20 72 65 61 64 65 72 73 2c 20 74 68 65 ase readers, the
4f450 0a 2a 2a 20 63 68 65 63 6b 70 6f 69 6e 74 20 6f .** checkpoint o
4f460 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
4f470 73 20 66 72 6f 6d 20 74 68 61 74 20 70 6f 69 6e s from that poin
4f480 74 20 69 6e 20 74 68 65 20 73 61 6d 65 20 77 61 t in the same wa
4f490 79 20 61 73 20 0a 2a 2a 20 53 51 4c 49 54 45 5f y as .** SQLITE_
4f4a0 43 48 45 43 4b 50 4f 49 4e 54 5f 50 41 53 53 49 CHECKPOINT_PASSI
4f4b0 56 45 20 2d 20 63 68 65 63 6b 70 6f 69 6e 74 69 VE - checkpointi
4f4c0 6e 67 20 61 73 20 6d 61 6e 79 20 66 72 61 6d 65 ng as many frame
4f4d0 73 20 61 73 20 70 6f 73 73 69 62 6c 65 20 0a 2a s as possible .*
4f4e0 2a 20 77 69 74 68 6f 75 74 20 62 6c 6f 63 6b 69 * without blocki
4f4f0 6e 67 20 61 6e 79 20 66 75 72 74 68 65 72 2e 20 ng any further.
4f500 53 51 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72 SQLITE_BUSY is r
4f510 65 74 75 72 6e 65 64 20 69 6e 20 74 68 69 73 20 eturned in this
4f520 63 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70 case..**.** If p
4f530 61 72 61 6d 65 74 65 72 20 7a 44 62 20 69 73 20 arameter zDb is
4f540 4e 55 4c 4c 20 6f 72 20 70 6f 69 6e 74 73 20 74 NULL or points t
4f550 6f 20 61 20 7a 65 72 6f 20 6c 65 6e 67 74 68 20 o a zero length
4f560 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 string, then the
4f570 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 6f 70 .** specified op
4f580 65 72 61 74 69 6f 6e 20 69 73 20 61 74 74 65 6d eration is attem
4f590 70 74 65 64 20 6f 6e 20 61 6c 6c 20 57 41 4c 20 pted on all WAL
4f5a0 64 61 74 61 62 61 73 65 73 2e 20 49 6e 20 74 68 databases. In th
4f5b0 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 76 is case the.** v
4f5c0 61 6c 75 65 73 20 77 72 69 74 74 65 6e 20 74 6f alues written to
4f5d0 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74 65 output paramete
4f5e0 72 73 20 2a 70 6e 4c 6f 67 20 61 6e 64 20 2a 70 rs *pnLog and *p
4f5f0 6e 43 6b 70 74 20 61 72 65 20 75 6e 64 65 66 69 nCkpt are undefi
4f600 6e 65 64 2e 20 49 66 20 0a 2a 2a 20 61 6e 20 53 ned. If .** an S
4f610 51 4c 49 54 45 5f 42 55 53 59 20 65 72 72 6f 72 QLITE_BUSY error
4f620 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 is encountered
4f630 77 68 65 6e 20 70 72 6f 63 65 73 73 69 6e 67 20 when processing
4f640 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
4f650 68 65 20 0a 2a 2a 20 61 74 74 61 63 68 65 64 20 he .** attached
4f660 57 41 4c 20 64 61 74 61 62 61 73 65 73 2c 20 74 WAL databases, t
4f670 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 he operation is
4f680 73 74 69 6c 6c 20 61 74 74 65 6d 70 74 65 64 20 still attempted
4f690 6f 6e 20 61 6e 79 20 72 65 6d 61 69 6e 69 6e 67 on any remaining
4f6a0 20 0a 2a 2a 20 61 74 74 61 63 68 65 64 20 64 61 .** attached da
4f6b0 74 61 62 61 73 65 73 20 61 6e 64 20 53 51 4c 49 tabases and SQLI
4f6c0 54 45 5f 42 55 53 59 20 69 73 20 72 65 74 75 72 TE_BUSY is retur
4f6d0 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 ned to the calle
4f6e0 72 2e 20 49 66 20 61 6e 79 20 6f 74 68 65 72 20 r. If any other
4f6f0 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 .** error occurs
4f700 20 77 68 69 6c 65 20 70 72 6f 63 65 73 73 69 6e while processin
4f710 67 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 g an attached da
4f720 74 61 62 61 73 65 2c 20 70 72 6f 63 65 73 73 69 tabase, processi
4f730 6e 67 20 69 73 20 61 62 61 6e 64 6f 6e 65 64 20 ng is abandoned
4f740 0a 2a 2a 20 61 6e 64 20 74 68 65 20 65 72 72 6f .** and the erro
4f750 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 r code returned
4f760 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 20 69 6d to the caller im
4f770 6d 65 64 69 61 74 65 6c 79 2e 20 49 66 20 6e 6f mediately. If no
4f780 20 65 72 72 6f 72 20 0a 2a 2a 20 28 53 51 4c 49 error .** (SQLI
4f790 54 45 5f 42 55 53 59 20 6f 72 20 6f 74 68 65 72 TE_BUSY or other
4f7a0 77 69 73 65 29 20 69 73 20 65 6e 63 6f 75 6e 74 wise) is encount
4f7b0 65 72 65 64 20 77 68 69 6c 65 20 70 72 6f 63 65 ered while proce
4f7c0 73 73 69 6e 67 20 74 68 65 20 61 74 74 61 63 68 ssing the attach
4f7d0 65 64 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 ed .** databases
4f7e0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 , SQLITE_OK is r
4f7f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
4f800 66 20 64 61 74 61 62 61 73 65 20 7a 44 62 20 69 f database zDb i
4f810 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e s the name of an
4f820 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
4f830 73 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69 se that is not i
4f840 6e 20 57 41 4c 0a 2a 2a 20 6d 6f 64 65 2c 20 53 n WAL.** mode, S
4f850 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
4f860 72 6e 65 64 20 61 6e 64 20 62 6f 74 68 20 2a 70 rned and both *p
4f870 6e 4c 6f 67 20 61 6e 64 20 2a 70 6e 43 6b 70 74 nLog and *pnCkpt
4f880 20 73 65 74 20 74 6f 20 2d 31 2e 20 49 66 0a 2a set to -1. If.*
4f890 2a 20 7a 44 62 20 69 73 20 6e 6f 74 20 4e 55 4c * zDb is not NUL
4f8a0 4c 20 28 6f 72 20 61 20 7a 65 72 6f 20 6c 65 6e L (or a zero len
4f8b0 67 74 68 20 73 74 72 69 6e 67 29 20 61 6e 64 20 gth string) and
4f8c0 69 73 20 6e 6f 74 20 74 68 65 20 6e 61 6d 65 20 is not the name
4f8d0 6f 66 20 61 6e 79 0a 2a 2a 20 61 74 74 61 63 68 of any.** attach
4f8e0 65 64 20 64 61 74 61 62 61 73 65 2c 20 53 51 4c ed database, SQL
4f8f0 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 ITE_ERROR is ret
4f900 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c urned to the cal
4f910 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ler..*/.SQLITE_A
4f920 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 77 PI int sqlite3_w
4f930 61 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 5f 76 32 al_checkpoint_v2
4f940 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
4f950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4f960 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
4f970 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
4f980 74 20 63 68 61 72 20 2a 7a 44 62 2c 20 20 20 20 t char *zDb,
4f990 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e /* N
4f9a0 61 6d 65 20 6f 66 20 61 74 74 61 63 68 65 64 20 ame of attached
4f9b0 64 61 74 61 62 61 73 65 20 28 6f 72 20 4e 55 4c database (or NUL
4f9c0 4c 29 20 2a 2f 0a 20 20 69 6e 74 20 65 4d 6f 64 L) */. int eMod
4f9d0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
4f9e0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 49 54 /* SQLIT
4f9f0 45 5f 43 48 45 43 4b 50 4f 49 4e 54 5f 2a 20 76 E_CHECKPOINT_* v
4fa00 61 6c 75 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 alue */. int *p
4fa10 6e 4c 6f 67 2c 20 20 20 20 20 20 20 20 20 20 20 nLog,
4fa20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
4fa30 3a 20 53 69 7a 65 20 6f 66 20 57 41 4c 20 6c 6f : Size of WAL lo
4fa40 67 20 69 6e 20 66 72 61 6d 65 73 20 2a 2f 0a 20 g in frames */.
4fa50 20 69 6e 74 20 2a 70 6e 43 6b 70 74 20 20 20 20 int *pnCkpt
4fa60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4fa70 20 2f 2a 20 4f 55 54 3a 20 54 6f 74 61 6c 20 6e /* OUT: Total n
4fa80 75 6d 62 65 72 20 6f 66 20 66 72 61 6d 65 73 20 umber of frames
4fa90 63 68 65 63 6b 70 6f 69 6e 74 65 64 20 2a 2f 0a checkpointed */.
4faa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
4fab0 45 46 3a 20 43 68 65 63 6b 70 6f 69 6e 74 20 6f EF: Checkpoint o
4fac0 70 65 72 61 74 69 6f 6e 20 70 61 72 61 6d 65 74 peration paramet
4fad0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ers.**.** These
4fae0 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 constants can be
4faf0 20 75 73 65 64 20 61 73 20 74 68 65 20 33 72 64 used as the 3rd
4fb00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
4fb10 20 5b 73 71 6c 69 74 65 33 5f 77 61 6c 5f 63 68 [sqlite3_wal_ch
4fb20 65 63 6b 70 6f 69 6e 74 5f 76 32 28 29 5d 2e 20 eckpoint_v2()].
4fb30 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 See the [sqlite
4fb40 33 5f 77 61 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 3_wal_checkpoint
4fb50 5f 76 32 28 29 5d 0a 2a 2a 20 64 6f 63 75 6d 65 _v2()].** docume
4fb60 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
4fb70 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
4fb80 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 6d 65 61 on about the mea
4fb90 6e 69 6e 67 20 61 6e 64 20 75 73 65 20 6f 66 0a ning and use of.
4fba0 2a 2a 20 65 61 63 68 20 6f 66 20 74 68 65 73 65 ** each of these
4fbb0 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 23 64 65 66 values..*/.#def
4fbc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 48 45 43 4b ine SQLITE_CHECK
4fbd0 50 4f 49 4e 54 5f 50 41 53 53 49 56 45 20 30 0a POINT_PASSIVE 0.
4fbe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
4fbf0 48 45 43 4b 50 4f 49 4e 54 5f 46 55 4c 4c 20 20 HECKPOINT_FULL
4fc00 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
4fc10 54 45 5f 43 48 45 43 4b 50 4f 49 4e 54 5f 52 45 TE_CHECKPOINT_RE
4fc20 53 54 41 52 54 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 START 2../*.** C
4fc30 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
4fc40 20 54 61 62 6c 65 20 49 6e 74 65 72 66 61 63 65 Table Interface
4fc50 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a Configuration.*
4fc60 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
4fc70 6f 6e 20 6d 61 79 20 62 65 20 63 61 6c 6c 65 64 on may be called
4fc80 20 62 79 20 65 69 74 68 65 72 20 74 68 65 20 5b by either the [
4fc90 78 43 6f 6e 6e 65 63 74 5d 20 6f 72 20 5b 78 43 xConnect] or [xC
4fca0 72 65 61 74 65 5d 20 6d 65 74 68 6f 64 0a 2a 2a reate] method.**
4fcb0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 of a [virtual t
4fcc0 61 62 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 able] implementa
4fcd0 74 69 6f 6e 20 74 6f 20 63 6f 6e 66 69 67 75 72 tion to configur
4fce0 65 0a 2a 2a 20 76 61 72 69 6f 75 73 20 66 61 63 e.** various fac
4fcf0 65 74 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 ets of the virtu
4fd00 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 al table interfa
4fd10 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 ce..**.** If thi
4fd20 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 s interface is i
4fd30 6e 76 6f 6b 65 64 20 6f 75 74 73 69 64 65 20 74 nvoked outside t
4fd40 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 61 6e he context of an
4fd50 20 78 43 6f 6e 6e 65 63 74 20 6f 72 0a 2a 2a 20 xConnect or.**
4fd60 78 43 72 65 61 74 65 20 76 69 72 74 75 61 6c 20 xCreate virtual
4fd70 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 74 68 65 table method the
4fd80 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
4fd90 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
4fda0 2a 2a 20 41 74 20 70 72 65 73 65 6e 74 2c 20 74 ** At present, t
4fdb0 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 6f 6e 65 here is only one
4fdc0 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 6d 61 79 option that may
4fdd0 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 20 75 be configured u
4fde0 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 66 75 6e sing.** this fun
4fdf0 63 74 69 6f 6e 2e 20 28 53 65 65 20 5b 53 51 4c ction. (See [SQL
4fe00 49 54 45 5f 56 54 41 42 5f 43 4f 4e 53 54 52 41 ITE_VTAB_CONSTRA
4fe10 49 4e 54 5f 53 55 50 50 4f 52 54 5d 2e 29 20 20 INT_SUPPORT].)
4fe20 46 75 72 74 68 65 72 20 6f 70 74 69 6f 6e 73 0a Further options.
4fe30 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ** may be added
4fe40 69 6e 20 74 68 65 20 66 75 74 75 72 65 2e 0a 2a in the future..*
4fe50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
4fe60 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 6f sqlite3_vtab_co
4fe70 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 nfig(sqlite3*, i
4fe80 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
4fe90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
4fea0 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 66 rtual Table Conf
4feb0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
4fec0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 s.**.** These ma
4fed0 63 72 6f 73 20 64 65 66 69 6e 65 20 74 68 65 20 cros define the
4fee0 76 61 72 69 6f 75 73 20 6f 70 74 69 6f 6e 73 20 various options
4fef0 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 to the.** [sqlit
4ff00 65 33 5f 76 74 61 62 5f 63 6f 6e 66 69 67 28 29 e3_vtab_config()
4ff10 5d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 ] interface that
4ff20 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
4ff30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
4ff40 0a 2a 2a 20 63 61 6e 20 75 73 65 20 74 6f 20 63 .** can use to c
4ff50 75 73 74 6f 6d 69 7a 65 20 61 6e 64 20 6f 70 74 ustomize and opt
4ff60 69 6d 69 7a 65 20 74 68 65 69 72 20 62 65 68 61 imize their beha
4ff70 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e vior..**.** <dl>
4ff80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 56 .** <dt>SQLITE_V
4ff90 54 41 42 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 53 TAB_CONSTRAINT_S
4ffa0 55 50 50 4f 52 54 0a 2a 2a 20 3c 64 64 3e 43 61 UPPORT.** <dd>Ca
4ffb0 6c 6c 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 0a lls of the form.
4ffc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 ** [sqlite3_vtab
4ffd0 5f 63 6f 6e 66 69 67 5d 28 64 62 2c 53 51 4c 49 _config](db,SQLI
4ffe0 54 45 5f 56 54 41 42 5f 43 4f 4e 53 54 52 41 49 TE_VTAB_CONSTRAI
4fff0 4e 54 5f 53 55 50 50 4f 52 54 2c 58 29 20 61 72 NT_SUPPORT,X) ar
50000 65 20 73 75 70 70 6f 72 74 65 64 2c 0a 2a 2a 20 e supported,.**
50010 77 68 65 72 65 20 58 20 69 73 20 61 6e 20 69 6e where X is an in
50020 74 65 67 65 72 2e 20 20 49 66 20 58 20 69 73 20 teger. If X is
50030 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b zero, then the [
50040 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 77 virtual table] w
50050 68 6f 73 65 0a 2a 2a 20 5b 78 43 72 65 61 74 65 hose.** [xCreate
50060 5d 20 6f 72 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 ] or [xConnect]
50070 6d 65 74 68 6f 64 20 69 6e 76 6f 6b 65 64 20 5b method invoked [
50080 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 6f 6e sqlite3_vtab_con
50090 66 69 67 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a fig()] does not.
500a0 2a 2a 20 73 75 70 70 6f 72 74 20 63 6f 6e 73 74 ** support const
500b0 72 61 69 6e 74 73 2e 20 20 49 6e 20 74 68 69 73 raints. In this
500c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 28 configuration (
500d0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
500e0 61 75 6c 74 29 20 69 66 0a 2a 2a 20 61 20 63 61 ault) if.** a ca
500f0 6c 6c 20 74 6f 20 74 68 65 20 5b 78 55 70 64 61 ll to the [xUpda
50100 74 65 5d 20 6d 65 74 68 6f 64 20 72 65 74 75 72 te] method retur
50110 6e 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ns [SQLITE_CONST
50120 52 41 49 4e 54 5d 2c 20 74 68 65 6e 20 74 68 65 RAINT], then the
50130 20 65 6e 74 69 72 65 0a 2a 2a 20 73 74 61 74 65 entire.** state
50140 6d 65 6e 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 ment is rolled b
50150 61 63 6b 20 61 73 20 69 66 20 5b 4f 4e 20 43 4f ack as if [ON CO
50160 4e 46 4c 49 43 54 20 7c 20 4f 52 20 41 42 4f 52 NFLICT | OR ABOR
50170 54 5d 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 73 T] had been.** s
50180 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 pecified as part
50190 20 6f 66 20 74 68 65 20 75 73 65 72 73 20 53 51 of the users SQ
501a0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 72 65 67 L statement, reg
501b0 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 61 ardless of the a
501c0 63 74 75 61 6c 0a 2a 2a 20 4f 4e 20 43 4f 4e 46 ctual.** ON CONF
501d0 4c 49 43 54 20 6d 6f 64 65 20 73 70 65 63 69 66 LICT mode specif
501e0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 58 20 ied..**.** If X
501f0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 is non-zero, the
50200 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 n the virtual ta
50210 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
50220 6f 6e 20 67 75 61 72 61 6e 74 65 65 73 0a 2a 2a on guarantees.**
50230 20 74 68 61 74 20 69 66 20 5b 78 55 70 64 61 74 that if [xUpdat
50240 65 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 e] returns [SQLI
50250 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5d 2c 20 TE_CONSTRAINT],
50260 69 74 20 77 69 6c 6c 20 64 6f 20 73 6f 20 62 65 it will do so be
50270 66 6f 72 65 0a 2a 2a 20 61 6e 79 20 6d 6f 64 69 fore.** any modi
50280 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 69 6e 74 fications to int
50290 65 72 6e 61 6c 20 6f 72 20 70 65 72 73 69 73 74 ernal or persist
502a0 65 6e 74 20 64 61 74 61 20 73 74 72 75 63 74 75 ent data structu
502b0 72 65 73 20 68 61 76 65 20 62 65 65 6e 20 6d 61 res have been ma
502c0 64 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 4f de..** If the [O
502d0 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 6d 6f 64 65 N CONFLICT] mode
502e0 20 69 73 20 41 42 4f 52 54 2c 20 46 41 49 4c 2c is ABORT, FAIL,
502f0 20 49 47 4e 4f 52 45 20 6f 72 20 52 4f 4c 4c 42 IGNORE or ROLLB
50300 41 43 4b 2c 20 53 51 4c 69 74 65 20 0a 2a 2a 20 ACK, SQLite .**
50310 69 73 20 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 20 is able to roll
50320 62 61 63 6b 20 61 20 73 74 61 74 65 6d 65 6e 74 back a statement
50330 20 6f 72 20 64 61 74 61 62 61 73 65 20 74 72 61 or database tra
50340 6e 73 61 63 74 69 6f 6e 2c 20 61 6e 64 20 61 62 nsaction, and ab
50350 61 6e 64 6f 6e 0a 2a 2a 20 6f 72 20 63 6f 6e 74 andon.** or cont
50360 69 6e 75 65 20 70 72 6f 63 65 73 73 69 6e 67 20 inue processing
50370 74 68 65 20 63 75 72 72 65 6e 74 20 53 51 4c 20 the current SQL
50380 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 70 70 statement as app
50390 72 6f 70 72 69 61 74 65 2e 20 0a 2a 2a 20 49 66 ropriate. .** If
503a0 20 74 68 65 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 the ON CONFLICT
503b0 20 6d 6f 64 65 20 69 73 20 52 45 50 4c 41 43 45 mode is REPLACE
503c0 20 61 6e 64 20 74 68 65 20 5b 78 55 70 64 61 74 and the [xUpdat
503d0 65 5d 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e e] method return
503e0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e s.** [SQLITE_CON
503f0 53 54 52 41 49 4e 54 5d 2c 20 53 51 4c 69 74 65 STRAINT], SQLite
50400 20 68 61 6e 64 6c 65 73 20 74 68 69 73 20 61 73 handles this as
50410 20 69 66 20 74 68 65 20 4f 4e 20 43 4f 4e 46 4c if the ON CONFL
50420 49 43 54 20 6d 6f 64 65 0a 2a 2a 20 68 61 64 20 ICT mode.** had
50430 62 65 65 6e 20 41 42 4f 52 54 2e 0a 2a 2a 0a 2a been ABORT..**.*
50440 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 * Virtual table
50450 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
50460 74 68 61 74 20 61 72 65 20 72 65 71 75 69 72 65 that are require
50470 64 20 74 6f 20 68 61 6e 64 6c 65 20 4f 52 20 52 d to handle OR R
50480 45 50 4c 41 43 45 0a 2a 2a 20 6d 75 73 74 20 64 EPLACE.** must d
50490 6f 20 73 6f 20 77 69 74 68 69 6e 20 74 68 65 20 o so within the
504a0 5b 78 55 70 64 61 74 65 5d 20 6d 65 74 68 6f 64 [xUpdate] method
504b0 2e 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 . If a call to t
504c0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f he .** [sqlite3_
504d0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 vtab_on_conflict
504e0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 ()] function ind
504f0 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 icates that the
50500 63 75 72 72 65 6e 74 20 4f 4e 20 0a 2a 2a 20 43 current ON .** C
50510 4f 4e 46 4c 49 43 54 20 70 6f 6c 69 63 79 20 69 ONFLICT policy i
50520 73 20 52 45 50 4c 41 43 45 2c 20 74 68 65 20 76 s REPLACE, the v
50530 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
50540 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
50550 6c 64 20 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 ld .** silently
50560 72 65 70 6c 61 63 65 20 74 68 65 20 61 70 70 72 replace the appr
50570 6f 70 72 69 61 74 65 20 72 6f 77 73 20 77 69 74 opriate rows wit
50580 68 69 6e 20 74 68 65 20 78 55 70 64 61 74 65 20 hin the xUpdate
50590 63 61 6c 6c 62 61 63 6b 20 61 6e 64 0a 2a 2a 20 callback and.**
505a0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
505b0 2e 20 4f 72 2c 20 69 66 20 74 68 69 73 20 69 73 . Or, if this is
505c0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 2c 20 69 not possible, i
505d0 74 20 6d 61 79 20 72 65 74 75 72 6e 0a 2a 2a 20 t may return.**
505e0 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
505f0 54 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 T, in which case
50600 20 53 51 4c 69 74 65 20 66 61 6c 6c 73 20 62 61 SQLite falls ba
50610 63 6b 20 74 6f 20 4f 52 20 41 42 4f 52 54 20 0a ck to OR ABORT .
50620 2a 2a 20 63 6f 6e 73 74 72 61 69 6e 74 20 68 61 ** constraint ha
50630 6e 64 6c 69 6e 67 2e 0a 2a 2a 20 3c 2f 64 6c 3e ndling..** </dl>
50640 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
50650 54 45 5f 56 54 41 42 5f 43 4f 4e 53 54 52 41 49 TE_VTAB_CONSTRAI
50660 4e 54 5f 53 55 50 50 4f 52 54 20 31 0a 0a 2f 2a NT_SUPPORT 1../*
50670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
50680 74 65 72 6d 69 6e 65 20 54 68 65 20 56 69 72 74 termine The Virt
50690 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 66 6c 69 ual Table Confli
506a0 63 74 20 50 6f 6c 69 63 79 0a 2a 2a 0a 2a 2a 20 ct Policy.**.**
506b0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 This function ma
506c0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 y only be called
506d0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 61 20 63 from within a c
506e0 61 6c 6c 20 74 6f 20 74 68 65 20 5b 78 55 70 64 all to the [xUpd
506f0 61 74 65 5d 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f ate] method.** o
50700 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 f a [virtual tab
50710 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 le] implementati
50720 6f 6e 20 66 6f 72 20 61 6e 20 49 4e 53 45 52 54 on for an INSERT
50730 20 6f 72 20 55 50 44 41 54 45 20 6f 70 65 72 61 or UPDATE opera
50740 74 69 6f 6e 2e 20 5e 54 68 65 0a 2a 2a 20 76 61 tion. ^The.** va
50750 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
50760 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 52 one of [SQLITE_R
50770 4f 4c 4c 42 41 43 4b 5d 2c 20 5b 53 51 4c 49 54 OLLBACK], [SQLIT
50780 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 E_IGNORE], [SQLI
50790 54 45 5f 46 41 49 4c 5d 2c 0a 2a 2a 20 5b 53 51 TE_FAIL],.** [SQ
507a0 4c 49 54 45 5f 41 42 4f 52 54 5d 2c 20 6f 72 20 LITE_ABORT], or
507b0 5b 53 51 4c 49 54 45 5f 52 45 50 4c 41 43 45 5d [SQLITE_REPLACE]
507c0 2c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 , according to t
507d0 68 65 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d he [ON CONFLICT]
507e0 20 6d 6f 64 65 0a 2a 2a 20 6f 66 20 74 68 65 20 mode.** of the
507f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
50800 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
50810 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 5b 78 55 call to the [xU
50820 70 64 61 74 65 5d 20 6d 65 74 68 6f 64 20 6f 66 pdate] method of
50830 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c the.** [virtual
50840 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 table]..*/.SQLI
50850 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
50860 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c e3_vtab_on_confl
50870 69 63 74 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a ict(sqlite3 *);.
50880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
50890 20 43 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 Conflict resolu
508a0 74 69 6f 6e 20 6d 6f 64 65 73 0a 2a 2a 0a 2a 2a tion modes.**.**
508b0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
508c0 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 62 79 are returned by
508d0 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f [sqlite3_vtab_o
508e0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 74 6f n_conflict()] to
508f0 0a 2a 2a 20 69 6e 66 6f 72 6d 20 61 20 5b 76 69 .** inform a [vi
50900 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 6d 70 rtual table] imp
50910 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 61 74 lementation what
50920 20 74 68 65 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 the [ON CONFLIC
50930 54 5d 20 6d 6f 64 65 0a 2a 2a 20 69 73 20 66 6f T] mode.** is fo
50940 72 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d r the SQL statem
50950 65 6e 74 20 62 65 69 6e 67 20 65 76 61 6c 75 61 ent being evalua
50960 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ted..**.** Note
50970 74 68 61 74 20 74 68 65 20 5b 53 51 4c 49 54 45 that the [SQLITE
50980 5f 49 47 4e 4f 52 45 5d 20 63 6f 6e 73 74 61 6e _IGNORE] constan
50990 74 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 t is also used a
509a0 73 20 61 20 70 6f 74 65 6e 74 69 61 6c 0a 2a 2a s a potential.**
509b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
509c0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
509d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
509e0 5d 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 ] callback and t
509f0 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 hat.** [SQLITE_A
50a00 42 4f 52 54 5d 20 69 73 20 61 6c 73 6f 20 61 20 BORT] is also a
50a10 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 0a 2a [result code]..*
50a20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
50a30 5f 52 4f 4c 4c 42 41 43 4b 20 31 0a 2f 2a 20 23 _ROLLBACK 1./* #
50a40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 define SQLITE_IG
50a50 4e 4f 52 45 20 32 20 2f 2f 20 41 6c 73 6f 20 75 NORE 2 // Also u
50a60 73 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 sed by sqlite3_a
50a70 75 74 68 6f 72 69 7a 65 72 28 29 20 63 61 6c 6c uthorizer() call
50a80 62 61 63 6b 20 2a 2f 0a 23 64 65 66 69 6e 65 20 back */.#define
50a90 53 51 4c 49 54 45 5f 46 41 49 4c 20 20 20 20 20 SQLITE_FAIL
50aa0 33 0a 2f 2a 20 23 64 65 66 69 6e 65 20 53 51 4c 3./* #define SQL
50ab0 49 54 45 5f 41 42 4f 52 54 20 34 20 20 2f 2f 20 ITE_ABORT 4 //
50ac0 41 6c 73 6f 20 61 6e 20 65 72 72 6f 72 20 63 6f Also an error co
50ad0 64 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 de */.#define SQ
50ae0 4c 49 54 45 5f 52 45 50 4c 41 43 45 20 20 35 0a LITE_REPLACE 5.
50af0 0a 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 .../*.** Undo th
50b00 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 e hack that conv
50b10 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f erts floating po
50b20 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69 6e 74 int types to int
50b30 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c eger for.** buil
50b40 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 ds on processors
50b50 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e without floatin
50b60 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e g point support.
50b70 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
50b80 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
50b90 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f POINT.# undef do
50ba0 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 uble.#endif..#if
50bb0 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a def __cplusplus.
50bc0 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 } /* End of the
50bd0 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c 'extern "C"' bl
50be0 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 ock */.#endif.#e
50bf0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 32 30 31 30 ndif../*.** 2010
50c00 20 41 75 67 75 73 74 20 33 30 0a 2a 2a 0a 2a 2a August 30.**.**
50c10 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 The author disc
50c20 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 laims copyright
50c30 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 to this source c
50c40 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f ode. In place o
50c50 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 f.** a legal not
50c60 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 ice, here is a b
50c70 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 lessing:.**.**
50c80 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f May you do goo
50c90 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a d and not evil..
50ca0 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 ** May you fi
50cb0 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 nd forgiveness f
50cc0 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 or yourself and
50cd0 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a forgive others..
50ce0 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 ** May you sh
50cf0 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 are freely, neve
50d00 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 r taking more th
50d10 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a an you give..**.
50d20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
50d30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
50d40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
50d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
50d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 23 69 *********.*/..#i
50d70 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 52 54 fndef _SQLITE3RT
50d80 52 45 45 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f REE_H_.#define _
50d90 53 51 4c 49 54 45 33 52 54 52 45 45 5f 48 5f 0a SQLITE3RTREE_H_.
50da0 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 ..#ifdef __cplus
50db0 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 plus.extern "C"
50dc0 7b 0a 23 65 6e 64 69 66 0a 0a 74 79 70 65 64 65 {.#endif..typede
50dd0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
50de0 5f 72 74 72 65 65 5f 67 65 6f 6d 65 74 72 79 20 _rtree_geometry
50df0 73 71 6c 69 74 65 33 5f 72 74 72 65 65 5f 67 65 sqlite3_rtree_ge
50e00 6f 6d 65 74 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 52 ometry;../*.** R
50e10 65 67 69 73 74 65 72 20 61 20 67 65 6f 6d 65 74 egister a geomet
50e20 72 79 20 63 61 6c 6c 62 61 63 6b 20 6e 61 6d 65 ry callback name
50e30 64 20 7a 47 65 6f 6d 20 74 68 61 74 20 63 61 6e d zGeom that can
50e40 20 62 65 20 75 73 65 64 20 61 73 20 70 61 72 74 be used as part
50e50 20 6f 66 20 61 6e 0a 2a 2a 20 52 2d 54 72 65 65 of an.** R-Tree
50e60 20 67 65 6f 6d 65 74 72 79 20 71 75 65 72 79 20 geometry query
50e70 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
50e80 2a 20 20 20 53 45 4c 45 43 54 20 2e 2e 2e 20 46 * SELECT ... F
50e90 52 4f 4d 20 3c 72 74 72 65 65 3e 20 57 48 45 52 ROM <rtree> WHER
50ea0 45 20 3c 72 74 72 65 65 20 63 6f 6c 3e 20 4d 41 E <rtree col> MA
50eb0 54 43 48 20 24 7a 47 65 6f 6d 28 2e 2e 2e 20 70 TCH $zGeom(... p
50ec0 61 72 61 6d 73 20 2e 2e 2e 29 0a 2a 2f 0a 53 51 arams ...).*/.SQ
50ed0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
50ee0 69 74 65 33 5f 72 74 72 65 65 5f 67 65 6f 6d 65 ite3_rtree_geome
50ef0 74 72 79 5f 63 61 6c 6c 62 61 63 6b 28 0a 20 20 try_callback(.
50f00 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
50f10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 47 65 6f 6d onst char *zGeom
50f20 2c 0a 20 20 69 6e 74 20 28 2a 78 47 65 6f 6d 29 ,. int (*xGeom)
50f30 28 73 71 6c 69 74 65 33 5f 72 74 72 65 65 5f 67 (sqlite3_rtree_g
50f40 65 6f 6d 65 74 72 79 20 2a 2c 20 69 6e 74 20 6e eometry *, int n
50f50 43 6f 6f 72 64 2c 20 64 6f 75 62 6c 65 20 2a 61 Coord, double *a
50f60 43 6f 6f 72 64 2c 20 69 6e 74 20 2a 70 52 65 73 Coord, int *pRes
50f70 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 6f 6e 74 ),. void *pCont
50f80 65 78 74 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 41 ext.);.../*.** A
50f90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 pointer to a st
50fa0 72 75 63 74 75 72 65 20 6f 66 20 74 68 65 20 66 ructure of the f
50fb0 6f 6c 6c 6f 77 69 6e 67 20 74 79 70 65 20 69 73 ollowing type is
50fc0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
50fd0 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 irst.** argument
50fe0 20 74 6f 20 63 61 6c 6c 62 61 63 6b 73 20 72 65 to callbacks re
50ff0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 72 gistered using r
51000 74 72 65 65 5f 67 65 6f 6d 65 74 72 79 5f 63 61 tree_geometry_ca
51010 6c 6c 62 61 63 6b 28 29 2e 0a 2a 2f 0a 73 74 72 llback()..*/.str
51020 75 63 74 20 73 71 6c 69 74 65 33 5f 72 74 72 65 uct sqlite3_rtre
51030 65 5f 67 65 6f 6d 65 74 72 79 20 7b 0a 20 20 76 e_geometry {. v
51040 6f 69 64 20 2a 70 43 6f 6e 74 65 78 74 3b 20 20 oid *pContext;
51050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
51060 2a 20 43 6f 70 79 20 6f 66 20 70 43 6f 6e 74 65 * Copy of pConte
51070 78 74 20 70 61 73 73 65 64 20 74 6f 20 73 5f 72 xt passed to s_r
51080 5f 67 5f 63 28 29 20 2a 2f 0a 20 20 69 6e 74 20 _g_c() */. int
51090 6e 50 61 72 61 6d 3b 20 20 20 20 20 20 20 20 20 nParam;
510a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
510b0 69 7a 65 20 6f 66 20 61 72 72 61 79 20 61 50 61 ize of array aPa
510c0 72 61 6d 5b 5d 20 2a 2f 0a 20 20 64 6f 75 62 6c ram[] */. doubl
510d0 65 20 2a 61 50 61 72 61 6d 3b 20 20 20 20 20 20 e *aParam;
510e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 61 /* Pa
510f0 72 61 6d 65 74 65 72 73 20 70 61 73 73 65 64 20 rameters passed
51100 74 6f 20 53 51 4c 20 67 65 6f 6d 20 66 75 6e 63 to SQL geom func
51110 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
51120 70 55 73 65 72 3b 20 20 20 20 20 20 20 20 20 20 pUser;
51130 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 61 6c /* Cal
51140 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 lback implementa
51150 74 69 6f 6e 20 75 73 65 72 20 64 61 74 61 20 2a tion user data *
51160 2f 0a 20 20 76 6f 69 64 20 28 2a 78 44 65 6c 55 /. void (*xDelU
51170 73 65 72 29 28 76 6f 69 64 20 2a 29 3b 20 20 20 ser)(void *);
51180 20 20 20 20 2f 2a 20 43 61 6c 6c 65 64 20 62 79 /* Called by
51190 20 53 51 4c 69 74 65 20 74 6f 20 63 6c 65 61 6e SQLite to clean
511a0 20 75 70 20 70 55 73 65 72 20 2a 2f 0a 7d 3b 0a up pUser */.};.
511b0 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 ..#ifdef __cplus
511c0 70 6c 75 73 0a 7d 20 20 2f 2a 20 65 6e 64 20 6f plus.} /* end o
511d0 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 f the 'extern "C
511e0 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 "' block */.#end
511f0 69 66 0a 0a 23 65 6e 64 69 66 20 20 2f 2a 20 69 if..#endif /* i
51200 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 52 54 fndef _SQLITE3RT
51210 52 45 45 5f 48 5f 20 2a 2f 0a 0a REE_H_ */..