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 6f 20 6d 61 6b 65 20 6d 69 6e 6f rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20 r changes if.**
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29 cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 33 2e 68 2c $Id: sqlite3.h,
05e0: 76 20 31 2e 33 39 20 32 30 30 39 2f 30 34 2f 32 v 1.39 2009/04/2
05f0: 38 20 31 36 3a 31 37 3a 34 35 20 72 6d 73 69 6d 8 16:17:45 rmsim
0600: 70 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23 69 pson Exp $.*/.#i
0610: 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 fndef _SQLITE3_H
0620: 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 _.#define _SQLIT
0630: 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c E3_H_.#include <
0640: 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a stdarg.h> /*
0650: 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 Needed for the
0660: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 definition of va
0670: 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 _list */../*.**
0680: 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e Make sure we can
0690: 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 call this stuff
06a0: 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 from C++..*/.#i
06b0: 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 fdef __cplusplus
06c0: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 .extern "C" {.#e
06d0: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 ndif.../*.** Add
06e0: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 the ability to
06f0: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e override 'extern
0700: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c '.*/.#ifndef SQL
0710: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 ITE_EXTERN.# def
0720: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 ine SQLITE_EXTER
0730: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a N extern.#endif.
0740: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d ./*.** These no-
0750: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 op macros are us
0760: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 ed in front of i
0770: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 nterfaces to mar
0780: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 k those.** inter
0790: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20 faces as either
07a0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 deprecated or ex
07b0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 perimental. New
07c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
07d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 should not use
07e0: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 72 66 deprecated intrf
07f0: 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 aces - they are
0800: 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b support for back
0810: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 wards.** compati
0820: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 bility only. Ap
0830: 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 plication writer
0840: 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 s should be awar
0850: 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 e that.** experi
0860: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 mental interface
0870: 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f s are subject to
0880: 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 change in point
0890: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a releases..**.**
08a0: 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 These macros us
08b0: 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f ed to resolve to
08c0: 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f various kinds o
08d0: 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 f compiler magic
08e0: 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 that.** would g
08f0: 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 enerate warning
0900: 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 messages when th
0910: 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 ey were used. B
0920: 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 ut that.** compi
0930: 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 ler magic ended
0940: 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 up generating su
0950: 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 ch a flurry of b
0960: 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 ug reports.** th
0970: 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e at we have taken
0980: 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 it all out and
0990: 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 gone back to usi
09a0: 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f ng simple.** noo
09b0: 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 p macros..*/.#de
09c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 fine SQLITE_DEPR
09d0: 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 ECATED.#define S
09e0: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
09f0: 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 AL../*.** Ensure
0a00: 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 these symbols w
0a10: 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 ere not defined
0a20: 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 by some previous
0a30: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f header file..*/
0a40: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 .#ifdef SQLITE_V
0a50: 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 ERSION.# undef S
0a60: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 QLITE_VERSION.#e
0a70: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 ndif.#ifdef SQLI
0a80: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0a90: 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 R.# undef SQLITE
0aa0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a _VERSION_NUMBER.
0ab0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
0ac0: 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
0ad0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 Time Library Ver
0ae0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 sion Numbers {H1
0af0: 30 30 31 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 0010} <S60100>.*
0b00: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
0b10: 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 VERSION and SQLI
0b20: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0b30: 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a R #defines in.**
0b40: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 66 the sqlite3.h f
0b50: 69 6c 65 20 73 70 65 63 69 66 79 20 74 68 65 20 ile specify the
0b60: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 version of SQLit
0b70: 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 e with which.**
0b80: 74 68 61 74 20 68 65 61 64 65 72 20 66 69 6c 65 that header file
0b90: 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a is associated..
0ba0: 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 73 69 **.** The "versi
0bb0: 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 69 73 on" of SQLite is
0bc0: 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74 68 65 a string of the
0bd0: 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a form "X.Y.Z"..*
0be0: 2a 20 54 68 65 20 70 68 72 61 73 65 20 22 61 6c * The phrase "al
0bf0: 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 20 6d pha" or "beta" m
0c00: 69 67 68 74 20 62 65 20 61 70 70 65 6e 64 65 64 ight be appended
0c10: 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a after the Z..**
0c20: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20 The X value is
0c30: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 major version nu
0c40: 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20 69 6e mber always 3 in
0c50: 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 SQLite3..** The
0c60: 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 X value only ch
0c70: 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63 6b 77 anges when backw
0c80: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
0c90: 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 ty is.** broken
0ca0: 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f and we intend to
0cb0: 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62 61 63 never break bac
0cc0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
0cd0: 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 lity..** The Y v
0ce0: 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69 6e 6f alue is the mino
0cf0: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 r version number
0d00: 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 and only change
0d10: 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 s when.** there
0d20: 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 are major featur
0d30: 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 e enhancements t
0d40: 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 hat are forwards
0d50: 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 compatible.** b
0d60: 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 ut not backwards
0d70: 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 compatible..**
0d80: 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 74 The Z value is t
0d90: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 he release numbe
0da0: 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 r and is increme
0db0: 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 nted with.** eac
0dc0: 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 65 h release but re
0dd0: 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77 sets back to 0 w
0de0: 68 65 6e 65 76 65 72 20 59 20 69 73 20 69 6e 63 henever Y is inc
0df0: 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 remented..**.**
0e00: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
0e10: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d e3_libversion()]
0e20: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 and [sqlite3_li
0e30: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
0e40: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
0e50: 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d ements: [H10011]
0e60: 20 5b 48 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 [H10014].*/.#de
0e70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 fine SQLITE_VERS
0e80: 49 4f 4e 20 20 20 20 20 20 20 20 20 22 33 2e 36 ION "3.6
0e90: 2e 31 33 22 0a 23 64 65 66 69 6e 65 20 53 51 4c .13".#define SQL
0ea0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0eb0: 45 52 20 20 33 30 30 36 30 31 33 0a 0a 2f 2a 0a ER 3006013../*.
0ec0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
0ed0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 -Time Library Ve
0ee0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 rsion Numbers {H
0ef0: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 10020} <S60100>.
0f00: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
0f10: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a ite3_version.**.
0f20: 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65 ** These feature
0f30: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 s provide the sa
0f40: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 me information a
0f50: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 s the [SQLITE_VE
0f60: 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 RSION].** and [S
0f70: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0f80: 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 MBER] #defines i
0f90: 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 n the header, bu
0fa0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 t are associated
0fb0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 .** with the lib
0fc0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 rary instead of
0fd0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e the header file.
0fe0: 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 Cautious progr
0ff0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 ammers might.**
1000: 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 include a check
1010: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 in their applica
1020: 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 tion to verify t
1030: 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c hat.** sqlite3_l
1040: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
1050: 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e () always return
1060: 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b s the value.** [
1070: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1080: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 UMBER]..**.** Th
1090: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 e sqlite3_libver
10a0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 sion() function
10b0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 returns the same
10c0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 information as
10d0: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c is.** in the sql
10e0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 ite3_version[] s
10f0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 tring constant.
1100: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 The function is
1110: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 provided.** for
1120: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e use in DLLs sin
1130: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 ce DLL users usu
1140: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 ally do not have
1150: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 direct access t
1160: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 o string.** cons
1170: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 tants within the
1180: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 DLL..**.** Requ
1190: 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32 irements: [H1002
11a0: 31 5d 20 5b 48 31 30 30 32 32 5d 20 5b 48 31 30 1] [H10022] [H10
11b0: 30 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 023].*/.SQLITE_E
11c0: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 XTERN const char
11d0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e sqlite3_version
11e0: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a [];.const char *
11f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1200: 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 on(void);.int sq
1210: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1220: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a _number(void);..
1230: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1240: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
1250: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
1260: 72 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30 readsafe {H10100
1270: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S60100>.**.**
1280: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 SQLite can be c
1290: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 ompiled with or
12a0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e without mutexes.
12b0: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 When.** the [S
12c0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
12d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
12e0: 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c 20 6d macro 1 or 2, m
12f0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e utexes.** are en
1300: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 abled and SQLite
1310: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 is threadsafe.
1320: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 When the.** [SQ
1330: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
1340: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a macro is 0, .**
1350: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 the mutexes are
1360: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f omitted. Witho
1370: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 ut the mutexes,
1380: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a it is not safe.*
1390: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 * to use SQLite
13a0: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f concurrently fro
13b0: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 m more than one
13c0: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e thread..**.** En
13d0: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 abling mutexes i
13e0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 ncurs a measurab
13f0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 le performance p
1400: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 enalty..** So if
1410: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d speed is of utm
1420: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 ost importance,
1430: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 it makes sense t
1440: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 o disable.** the
1450: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 mutexes. But f
1460: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 or maximum safet
1470: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c y, mutexes shoul
1480: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a d be enabled..**
1490: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 The default beh
14a0: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 avior is for mut
14b0: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c exes to be enabl
14c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ed..**.** This i
14d0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
14e0: 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 61 used by a progra
14f0: 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 m to make sure t
1500: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 hat the.** versi
1510: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 on of SQLite tha
1520: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 t it is linking
1530: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 against was comp
1540: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
1550: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 desired setting
1560: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
1570: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 THREADSAFE] macr
1580: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e o..**.** This in
1590: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 terface only rep
15a0: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 orts on the comp
15b0: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 ile-time mutex s
15c0: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 etting.** of the
15d0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
15e0: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 AFE] flag. If S
15f0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
1600: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 d with.** SQLITE
1610: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68 _THREADSAFE=1 th
1620: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 en mutexes are e
1630: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
1640: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 t but.** can be
1650: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c fully or partial
1660: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e ly disabled usin
1670: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c g a call to [sql
1680: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a ite3_config()].*
1690: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 * with the verbs
16a0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
16b0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b SINGLETHREAD], [
16c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
16d0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f LTITHREAD],.** o
16e0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
16f0: 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65 _MUTEX]. The re
1700: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
1710: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 is function show
1720: 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 s.** only the de
1730: 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 fault compile-ti
1740: 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 me setting, not
1750: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 any run-time cha
1760: 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 nges.** to that
1770: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 setting..**.** S
1780: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
1790: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
17a0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
17b0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
17c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
17d0: 65 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b ents: [H10101] [
17e0: 48 31 30 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73 H10102].*/.int s
17f0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
1800: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 e(void);../*.**
1810: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
1820: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 se Connection Ha
1830: 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 ndle {H12000} <S
1840: 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 40200>.** KEYWOR
1850: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f DS: {database co
1860: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 nnection} {datab
1870: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d ase connections}
1880: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e .**.** Each open
1890: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
18a0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 is represented
18b0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 by a pointer to
18c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a an instance of.*
18d0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 * the opaque str
18e0: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 ucture named "sq
18f0: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 lite3". It is u
1900: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f seful to think o
1910: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 f an sqlite3.**
1920: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 pointer as an ob
1930: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 ject. The [sqli
1940: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
1950: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
1960: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
1970: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
1980: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 rfaces are its c
1990: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 onstructors, and
19a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
19b0: 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 )].** is its des
19c0: 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 tructor. There
19d0: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 are many other i
19e0: 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 nterfaces (such
19f0: 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 as.** [sqlite3_p
1a00: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
1a10: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
1a20: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a nction()], and.*
1a30: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f * [sqlite3_busy_
1a40: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 timeout()] to na
1a50: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 me but three) th
1a60: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f at are methods o
1a70: 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 n an.** sqlite3
1a80: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 object..*/.typed
1a90: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1aa0: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 3 sqlite3;../*.*
1ab0: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 * CAPI3REF: 64-B
1ac0: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 it Integer Types
1ad0: 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 {H10200} <S1011
1ae0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
1af0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
1b00: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a ite_uint64.**.**
1b10: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 Because there i
1b20: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 s no cross-platf
1b30: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 orm way to speci
1b40: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 fy 64-bit intege
1b50: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 r types.** SQLit
1b60: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 e includes typed
1b70: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 efs for 64-bit s
1b80: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e igned and unsign
1b90: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a ed integers..**.
1ba0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
1bb0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 nt64 and sqlite3
1bc0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 _uint64 are the
1bd0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 preferred type d
1be0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 efinitions..** T
1bf0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 he sqlite_int64
1c00: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
1c10: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 4 types are supp
1c20: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 orted for backwa
1c30: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 rds.** compatibi
1c40: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a lity only..**.**
1c50: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
1c60: 48 31 30 32 30 31 5d 20 5b 48 31 30 32 30 32 5d H10201] [H10202]
1c70: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
1c80: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 E_INT64_TYPE. t
1c90: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e ypedef SQLITE_IN
1ca0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
1cb0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 int64;. typedef
1cc0: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 unsigned SQLITE
1cd0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
1ce0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 te_uint64;.#elif
1cf0: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 defined(_MSC_VE
1d00: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f R) || defined(__
1d10: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 BORLANDC__). ty
1d20: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 pedef __int64 sq
1d30: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
1d40: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f pedef unsigned _
1d50: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
1d60: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 nt64;.#else. ty
1d70: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 pedef long long
1d80: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 int sqlite_int64
1d90: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
1da0: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 gned long long i
1db0: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nt sqlite_uint64
1dc0: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 ;.#endif.typedef
1dd0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 sqlite_int64 sq
1de0: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 lite3_int64;.typ
1df0: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 edef sqlite_uint
1e00: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 64 sqlite3_uint6
1e10: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 4;../*.** If com
1e20: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f piling for a pro
1e30: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b cessor that lack
1e40: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 s floating point
1e50: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 support,.** sub
1e60: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 stitute integer
1e70: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 for floating-poi
1e80: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 nt..*/.#ifdef SQ
1e90: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 LITE_OMIT_FLOATI
1ea0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e NG_POINT.# defin
1eb0: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 e double sqlite3
1ec0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f _int64.#endif../
1ed0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
1ee0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 losing A Databas
1ef0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 e Connection {H1
1f00: 32 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 2010} <S30100><S
1f10: 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 40200>.**.** Thi
1f20: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 s routine is the
1f30: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 destructor for
1f40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
1f50: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c ject..**.** Appl
1f60: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
1f70: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1f80: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c e | finalize] al
1f90: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
1fa0: 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b ements].** and [
1fb0: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
1fc0: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 se | close] all
1fd0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 [BLOB handles] a
1fe0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a ssociated with.*
1ff0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 * the [sqlite3]
2000: 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 object prior to
2010: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c attempting to cl
2020: 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a ose the object..
2030: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
2040: 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 next_stmt()] int
2050: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2060: 65 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c ed to locate all
2070: 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
2080: 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 atements] associ
2090: 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 ated with a [dat
20a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20b0: 5d 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a ] if desired..**
20c0: 20 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 Typical code mi
20d0: 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 ght look like th
20e0: 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b is:.**.** <block
20f0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 quote><pre>.** s
2100: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2110: 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 mt;.** while( (p
2120: 53 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e Stmt = sqlite3_n
2130: 65 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 ext_stmt(db, 0))
2140: 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b !=0 ){.**
2150: 20 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c sqlite3_final
2160: 69 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d ize(pStmt);.** }
2170: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
2180: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 kquote>.**.** If
2190: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
21a0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 )] is invoked wh
21b0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f ile a transactio
21c0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 n is open,.** th
21d0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 e transaction is
21e0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
21f0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
2200: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 * The C paramete
2210: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c r to [sqlite3_cl
2220: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 ose(C)] must be
2230: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a either a NULL.**
2240: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b pointer or an [
2250: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2260: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 pointer obtained
2270: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
2280: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
2290: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f te3_open16()], o
22a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
22b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f en_v2()], and no
22c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f t previously clo
22d0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 sed..**.** Requi
22e0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
22f0: 30 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 011] [H12012] [H
2300: 31 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 12013] [H12014]
2310: 5b 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31 39 [H12015] [H12019
2320: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
2330: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a _close(sqlite3 *
2340: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
2350: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
2360: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
2370: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
2380: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
2390: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
23a0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
23b0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
23c0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
23d0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
23e0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
23f0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
2400: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
2410: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2420: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
2430: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
2440: 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20 erface {H12100}
2450: 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S10000>.**.** T
2460: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
2470: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 ) interface is a
2480: 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 convenient way
2490: 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f of running one o
24a0: 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 r more.** SQL st
24b0: 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 atements without
24c0: 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 having to write
24d0: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 a lot of C code
24e0: 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 . The UTF-8 enc
24f0: 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 oded.** SQL stat
2500: 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 ements are passe
2510: 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f d in as the seco
2520: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
2530: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a sqlite3_exec()..
2540: 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 ** The statement
2550: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 s are evaluated
2560: 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c one by one until
2570: 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 either an error
2580: 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 or.** an interr
2590: 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 upt is encounter
25a0: 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ed, or until the
25b0: 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 y are all done.
25c0: 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 The 3rd paramet
25d0: 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 er.** is an opti
25e0: 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 onal callback th
25f0: 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e at is invoked on
2600: 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 ce for each row
2610: 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 of any query.**
2620: 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 results produced
2630: 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 by the SQL stat
2640: 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 ements. The 5th
2650: 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 parameter tells
2660: 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 where.** to wri
2670: 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 te any error mes
2680: 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 sages..**.** The
2690: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 error message p
26a0: 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 assed back throu
26b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
26c0: 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 eter is held.**
26d0: 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e in memory obtain
26e0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
26f0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 _malloc()]. To
2700: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c avoid a memory l
2710: 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c eak,.** the call
2720: 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ing application
2730: 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c should call [sql
2740: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 ite3_free()] on
2750: 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 any error.** mes
2760: 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 sage returned th
2770: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 rough the 5th pa
2780: 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 rameter when it
2790: 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
27a0: 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 ng.** the error
27b0: 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 message..**.** I
27c0: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
27d0: 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 ent in the 2nd p
27e0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c arameter is NULL
27f0: 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 or an empty str
2800: 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 ing.** or a stri
2810: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e ng containing on
2820: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e ly whitespace an
2830: 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e d comments, then
2840: 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 no SQL.** state
2850: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 ments are evalua
2860: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 ted and the data
2870: 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e base is not chan
2880: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ged..**.** The s
2890: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e qlite3_exec() in
28a0: 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 terface is imple
28b0: 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 mented in terms
28c0: 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 of.** [sqlite3_p
28d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
28e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
28f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e and [sqlite3_fin
2900: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 alize()]..** The
2910: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
2920: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 routine does not
2930: 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 hing to the data
2940: 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 base that cannot
2950: 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b be done.** by [
2960: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2970: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
2980: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 step()], and [sq
2990: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
29a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
29b0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
29c0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
29d0: 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 must be an vali
29e0: 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b 64 d and open.** [d
29f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2a00: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 on]..**.** The d
2a10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2a20: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 on must not be c
2a30: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 5b losed while.** [
2a40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
2a50: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a is running..**.*
2a60: 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 * The calling fu
2a70: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 nction should us
2a80: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
2a90: 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 74 68 )] to free.** th
2aa0: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 e memory that *e
2ab0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f rrmsg is left po
2ac0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 inting at once t
2ad0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 he error.** mess
2ae0: 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 age is no longer
2af0: 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 needed..**.** T
2b00: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2b10: 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 text in the 2nd
2b20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
2b30: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a qlite3_exec()].*
2b40: 2a 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e * must remain un
2b50: 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 changed while [s
2b60: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 qlite3_exec()] i
2b70: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
2b80: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
2b90: 2a 20 5b 48 31 32 31 30 31 5d 20 5b 48 31 32 31 * [H12101] [H121
2ba0: 30 32 5d 20 5b 48 31 32 31 30 34 5d 20 5b 48 31 02] [H12104] [H1
2bb0: 32 31 30 35 5d 20 5b 48 31 32 31 30 37 5d 20 5b 2105] [H12107] [
2bc0: 48 31 32 31 31 30 5d 20 5b 48 31 32 31 31 33 5d H12110] [H12113]
2bd0: 20 5b 48 31 32 31 31 36 5d 0a 2a 2a 20 5b 48 31 [H12116].** [H1
2be0: 32 31 31 39 5d 20 5b 48 31 32 31 32 32 5d 20 5b 2119] [H12122] [
2bf0: 48 31 32 31 32 35 5d 20 5b 48 31 32 31 33 31 5d H12125] [H12131]
2c00: 20 5b 48 31 32 31 33 34 5d 20 5b 48 31 32 31 33 [H12134] [H1213
2c10: 37 5d 20 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a 69 7] [H12138].*/.i
2c20: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 nt sqlite3_exec(
2c30: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 . sqlite3*,
2c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2c60: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
2c70: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2c80: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 r *sql,
2c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ca0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
2cb0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e valuated */. in
2cc0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f t (*callback)(vo
2cd0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 id*,int,char**,c
2ce0: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c har**), /* Call
2cf0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f back function */
2d00: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
2d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2d30: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 1st argument to
2d40: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 callback */. c
2d50: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 har **errmsg
2d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
2d80: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
2d90: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ere */.);../*.**
2da0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
2db0: 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d t Codes {H10210}
2dc0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 <S10700>.** KEY
2dd0: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b WORDS: SQLITE_OK
2de0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 {error code} {e
2df0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
2e00: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 EYWORDS: {result
2e10: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 code} {result c
2e20: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 odes}.**.** Many
2e30: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
2e40: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 s return an inte
2e50: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ger result code
2e60: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f from the set sho
2e70: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 wn.** here in or
2e80: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 der to indicates
2e90: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
2ea0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
2eb0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
2ec0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
2ed0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
2ee0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
2ef0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
2f00: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
2f10: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
2f20: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ].*/.#define SQL
2f30: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
2f40: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
2f50: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
2f60: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
2f70: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
2f80: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
2f90: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
2fa0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
2fb0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
2fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
2fd0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
2fe0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
2ff0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
3000: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3010: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
3020: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
3030: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
3040: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3050: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
3060: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
3070: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
3080: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
3090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
30a0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
30b0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
30c0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
30d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
30e0: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
30f0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
3100: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
3110: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
3120: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
3130: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
3140: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
3150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
3160: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
3170: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
3180: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
3190: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
31a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
31b0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
31c0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
31d0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
31e0: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
31f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3200: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
3210: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
3220: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
3230: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
3240: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
3250: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
3260: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
3270: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
3280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3290: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
32a0: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 /* NOT USED. T
32b0: 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e able or record n
32c0: 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 ot found */.#def
32d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 ine SQLITE_FULL
32e0: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 13 /* I
32f0: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 nsertion failed
3300: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 because database
3310: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 is full */.#def
3320: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
3330: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 PEN 14 /* U
3340: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
3350: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
3360: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3370: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 E_PROTOCOL 15
3380: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 /* NOT USED.
3390: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
33a0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
33b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
33c0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
33d0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 /* Database is e
33e0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 mpty */.#define
33f0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
3400: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
3410: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
3420: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
3430: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
3440: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
3450: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
3460: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
3470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3480: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
3490: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
34a0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
34b0: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
34c0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
34d0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
34e0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
34f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3500: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
3510: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
3520: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
3530: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3540: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
3550: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
3560: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
3570: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
3580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
3590: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
35a0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
35b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
35c0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
35d0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 24 /* Aux
35e0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 iliary database
35f0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a format error */.
3600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
3610: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 ANGE 25
3620: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 /* 2nd parameter
3630: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
3640: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f out of range */
3650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3660: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 NOTADB 26
3670: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 /* File opened
3680: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 that is not a da
3690: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
36a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f define SQLITE_RO
36b0: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f W 100 /
36c0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
36d0: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 has another row
36e0: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e ready */.#defin
36f0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 e SQLITE_DONE
3700: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 101 /* sql
3710: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
3720: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
3730: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d ng */./* end-of-
3740: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a error-codes */..
3750: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3760: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
3770: 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c Codes {H10220} <
3780: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10700>.** KEYWO
3790: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 RDS: {extended e
37a0: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 rror code} {exte
37b0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
37c0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
37d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
37e0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 code} {extended
37f0: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a result codes}.**
3800: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 .** In its defau
3810: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
3820: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 , SQLite API rou
3830: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 tines return one
3840: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a of 26 integer.*
3850: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 * [SQLITE_OK | r
3860: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 esult codes]. H
3870: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e owever, experien
3880: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 ce has shown tha
3890: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 t many of.** the
38a0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 se result codes
38b0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 are too coarse-g
38c0: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f rained. They do
38d0: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a not provide as.
38e0: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 ** much informat
38f0: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 ion about proble
3900: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 ms as programmer
3910: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 s might like. I
3920: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a n an effort to.*
3930: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 * address this,
3940: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
3950: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f f SQLite (versio
3960: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 n 3.3.8 and late
3970: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 r) include.** su
3980: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 pport for additi
3990: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 onal result code
39a0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d s that provide m
39b0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 ore detailed inf
39c0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
39d0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 t errors. The ex
39e0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
39f0: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 des are enabled
3a00: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f or disabled.** o
3a10: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 n a per database
3a20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 connection basi
3a30: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b s using the.** [
3a40: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
3a50: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d _result_codes()]
3a60: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 API..**.** Some
3a70: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c of the availabl
3a80: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
3a90: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 t codes are list
3aa0: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 ed here..** One
3ab0: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e may expect the n
3ac0: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 umber of extende
3ad0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 d result codes w
3ae0: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a ill be expand.**
3af0: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 over time. Sof
3b00: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 tware that uses
3b10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
3b20: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 codes should exp
3b30: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 ect.** to see ne
3b40: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 w result codes i
3b50: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
3b60: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
3b70: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b ** The SQLITE_OK
3b80: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c result code wil
3b90: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e l never be exten
3ba0: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c ded. It will al
3bb0: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 ways.** be exact
3bc0: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 ly zero..*/.#def
3bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3be0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
3bf0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
3c00: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
3c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
3c20: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 SHORT_READ
3c30: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
3c40: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
3c50: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 e SQLITE_IOERR_W
3c60: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
3c70: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
3c80: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
3c90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
3ca0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 YNC
3cb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
3cc0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
3cd0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
3ce0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 _FSYNC (
3cf0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
3d00: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
3d10: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e QLITE_IOERR_TRUN
3d20: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 CATE (S
3d30: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 QLITE_IOERR | (6
3d40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
3d50: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 LITE_IOERR_FSTAT
3d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
3d70: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c LITE_IOERR | (7<
3d80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
3d90: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b ITE_IOERR_UNLOCK
3da0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
3db0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c ITE_IOERR | (8<<
3dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3dd0: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 TE_IOERR_RDLOCK
3de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
3df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 TE_IOERR | (9<<8
3e00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3e10: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 E_IOERR_DELETE
3e20: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3e30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 E_IOERR | (10<<8
3e40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3e50: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 E_IOERR_BLOCKED
3e60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3e70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 E_IOERR | (11<<8
3e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3e90: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 E_IOERR_NOMEM
3ea0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3eb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 E_IOERR | (12<<8
3ec0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3ed0: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 E_IOERR_ACCESS
3ee0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3ef0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 E_IOERR | (13<<8
3f00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3f10: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 E_IOERR_CHECKRES
3f20: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 ERVEDLOCK (SQLIT
3f30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 E_IOERR | (14<<8
3f40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3f50: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 E_IOERR_LOCK
3f60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3f70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 E_IOERR | (15<<8
3f80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3f90: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 E_IOERR_CLOSE
3fa0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3fb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 E_IOERR | (16<<8
3fc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3fd0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 E_IOERR_DIR_CLOS
3fe0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 E (SQLIT
3ff0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 E_IOERR | (17<<8
4000: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4010: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 E_LOCKED_SHAREDC
4020: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 ACHE (SQLIT
4030: 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 E_LOCKED | (1<<8
4040: 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ) )../*.** CAPI3
4050: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 REF: Flags For F
4060: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 ile Open Operati
4070: 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 ons {H10230} <H1
4080: 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 1120> <H12700>.*
4090: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 *.** These bit v
40a0: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 alues are intend
40b0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 ed for use in th
40c0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 e.** 3rd paramet
40d0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
40e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
40f0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 terface and.** i
4100: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 n the 4th parame
4110: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ter to the xOpen
4120: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a method of the.*
4130: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
4140: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
4150: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
4160: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 EADONLY
4170: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
4180: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
4190: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 EADWRITE
41a0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ne SQLITE_OPEN_C
41c0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 REATE
41d0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
41e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 ne SQLITE_OPEN_D
41f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 ELETEONCLOSE
4200: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 0x00000008.#defi
4210: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 ne SQLITE_OPEN_E
4220: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 XCLUSIVE
4230: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
4240: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
4250: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 AIN_DB
4260: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
4270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
4280: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 EMP_DB
4290: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 0x00000200.#defi
42a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
42b0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 RANSIENT_DB
42c0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 0x00000400.#defi
42d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
42e0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 AIN_JOURNAL
42f0: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 0x00000800.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
4310: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 EMP_JOURNAL
4320: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 0x00001000.#defi
4330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
4340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 UBJOURNAL
4350: 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 0x00002000.#defi
4360: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
4370: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 ASTER_JOURNAL
4380: 30 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 0x00004000.#defi
4390: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e ne SQLITE_OPEN_N
43a0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 OMUTEX
43b0: 30 78 30 30 30 30 38 30 30 30 0a 23 64 65 66 69 0x00008000.#defi
43c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 ne SQLITE_OPEN_F
43d0: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 ULLMUTEX
43e0: 30 78 30 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 0x00010000../*.*
43f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
4400: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
4410: 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 cs {H10240} <H11
4420: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 120>.**.** The x
4430: 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 DeviceCapabiliti
4440: 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 es method of the
4450: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
4460: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 hods].** object
4470: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
4480: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 er which is a ve
4490: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 ctor of the thes
44a0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 e.** bit values
44b0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 expressing I/O c
44c0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f haracteristics o
44d0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 f the mass stora
44e0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 ge.** device tha
44f0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 t holds the file
4500: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 that the [sqlit
4510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
4520: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a * refers to..**.
4530: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f ** The SQLITE_IO
4540: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 CAP_ATOMIC prope
4550: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 rty means that a
4560: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 ll writes of.**
4570: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f any size are ato
4580: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
4590: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e _IOCAP_ATOMICnnn
45a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 values.** mean
45b0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 that writes of b
45c0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e locks that are n
45d0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 nn bytes in size
45e0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 and.** are alig
45f0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 ned to an addres
4600: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e s which is an in
4610: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f teger multiple o
4620: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f f.** nnn are ato
4630: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
4640: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
4650: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a ND value means.*
4660: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 * that when data
4670: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 is appended to
4680: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 a file, the data
4690: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 is appended.**
46a0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 first then the s
46b0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ize of the file
46c0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 is extended, nev
46d0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 er the other.**
46e0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 way around. The
46f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
4700: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 QUENTIAL propert
4710: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
4720: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 information is w
4730: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 ritten to disk i
4740: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 n the same order
4750: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 as calls.** to
4760: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 xWrite()..*/.#de
4770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4780: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 P_ATOMIC
4790: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 0x00000001.#de
47a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
47b0: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 P_ATOMIC512
47c0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 0x00000002.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
47e0: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 P_ATOMIC1K
47f0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
4800: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4810: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
4820: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 0x00000008.#de
4830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4840: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 P_ATOMIC4K
4850: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 0x00000010.#de
4860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4870: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 P_ATOMIC8K
4880: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
4890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
48a0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
48b0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
48c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
48d0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
48e0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 0x00000080.#de
48f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4900: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 P_ATOMIC64K
4910: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 0x00000100.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4930: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 P_SAFE_APPEND
4940: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 0x00000200.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4960: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 P_SEQUENTIAL
4970: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0x00000400../*
4980: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
4990: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c le Locking Level
49a0: 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 s {H10250} <H111
49b0: 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 20> <H11310>.**.
49c0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
49d0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
49e0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
49f0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
4a00: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
4a10: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
4a20: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
4a30: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
4a40: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
4a50: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
4a60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
4a70: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
4a80: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
4a90: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
4aa0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
4ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
4ac0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
4ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ae0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
4af0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
4b00: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
4b10: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
4b20: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
4b30: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
4b40: 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 lags {H10260} <H
4b50: 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 11120>.**.** Whe
4b60: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
4b70: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
4b80: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
4b90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
4ba0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
4bb0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
4bc0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
4bd0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
4be0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
4bf0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
4c00: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
4c10: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
4c20: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
4c30: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
4c40: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
4c50: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
4c60: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
4c70: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
4c80: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
4c90: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 be flushed. If
4ca0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
4cb0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a its of the flag.
4cc0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ** equal SQLITE_
4cd0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 SYNC_NORMAL, tha
4ce0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e t means to use n
4cf0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
4d00: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 mantics..** If t
4d10: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
4d20: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ts equal SQLITE_
4d30: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 SYNC_FULL, that
4d40: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
4d50: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
4d60: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
4d70: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 of fsync()..*/.#
4d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
4d90: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 NC_NORMAL
4da0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 0x00002.#define
4db0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
4dc0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 L 0x000
4dd0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 03.#define SQLIT
4de0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
4df0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0x00010../*
4e00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
4e10: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 Interface Open
4e20: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 File Handle {H11
4e30: 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 110} <S20110>.**
4e40: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
4e50: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
4e60: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
4e70: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a file in the OS.*
4e80: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 * interface laye
4e90: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f r. Individual O
4ea0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c S interface impl
4eb0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
4ec0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
4ed0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
4ee0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
4ef0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
4f00: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
4f10: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
4f20: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
4f30: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
4f40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
4f50: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
4f60: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
4f70: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
4f80: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
4f90: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
4fa0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
4fb0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
4fc0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
4fd0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
4fe0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
4ff0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
5000: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
5010: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
5020: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
5030: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
5040: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
5050: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
5060: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
5070: 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31 {H11120} <S2011
5080: 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 0>.**.** Every f
5090: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 ile opened by th
50a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
50b0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 xOpen method pop
50c0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 ulates an.** [sq
50d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
50e0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d ct (or, more com
50f0: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 monly, a subclas
5100: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c s of the.** [sql
5110: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
5120: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 t) with a pointe
5130: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
5140: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e of this object.
5150: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
5160: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 defines the meth
5170: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 ods used to perf
5180: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 orm various oper
5190: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 ations.** agains
51a0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 t the open file
51b0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 represented by t
51c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
51d0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
51e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
51f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 nt to xSync may
5200: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 be one of [SQLIT
5210: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f E_SYNC_NORMAL] o
5220: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e r.** [SQLITE_SYN
5230: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 C_FULL]. The fi
5240: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 rst choice is th
5250: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 e normal fsync()
5260: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
5270: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 choice is a Mac
5280: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS X style fulls
5290: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ync. The [SQLIT
52a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d E_SYNC_DATAONLY]
52b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 .** flag may be
52c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 ORed in to indic
52d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 ate that only th
52e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 e data of the fi
52f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 le.** and not it
5300: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f s inode needs to
5310: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a be synced..**.*
5320: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 * The integer va
5330: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 lues to xLock()
5340: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 and xUnlock() ar
5350: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e e one of.** <ul>
5360: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
5370: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 _LOCK_NONE],.**
5380: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
5390: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c K_SHARED],.** <l
53a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
53b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c RESERVED],.** <l
53c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
53d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 PENDING], or.**
53e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
53f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a K_EXCLUSIVE]..**
5400: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 </ul>.** xLock(
5410: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 ) increases the
5420: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 lock. xUnlock()
5430: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f decreases the lo
5440: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 ck..** The xChec
5450: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 kReservedLock()
5460: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 method checks wh
5470: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 ether any databa
5480: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a se connection,.*
5490: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 * either in this
54a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 process or in s
54b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 ome other proces
54c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 s, is holding a
54d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e RESERVED,.** PEN
54e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 DING, or EXCLUSI
54f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 VE lock on the f
5500: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 ile. It returns
5510: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 true.** if such
5520: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 a lock exists a
5530: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 nd false otherwi
5540: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 se..**.** The xF
5550: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 ileControl() met
5560: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 hod is a generic
5570: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
5580: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a allows custom.**
5590: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
55a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 ions to directly
55b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e control an open
55c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a file using the.
55d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
55e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 _control()] inte
55f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f rface. The seco
5600: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 nd "op" argument
5610: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 is an.** intege
5620: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 r opcode. The t
5630: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
5640: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 a generic point
5650: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a er intended to.*
5660: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 * point to a str
5670: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 ucture that may
5680: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 contain argument
5690: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 s or space in wh
56a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 ich to.** write
56b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 return values.
56c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 Potential uses f
56d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 or xFileControl(
56e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 ) might be.** fu
56f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c nctions to enabl
5700: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 e blocking locks
5710: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 with timeouts,
5720: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a to change the.**
5730: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 locking strateg
5740: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 y (for example t
5750: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c o use dot-file l
5760: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 ocks), to inquir
5770: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 e.** about the s
5780: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c tatus of a lock,
5790: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 or to break sta
57a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 le locks. The S
57b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 QLite.** core re
57c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 serves all opcod
57d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 es less than 100
57e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 for its own use
57f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 ..** A [SQLITE_F
5800: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c CNTL_LOCKSTATE |
5810: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 list of opcodes
5820: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 ] less than 100
5830: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a is available..**
5840: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
5850: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 at define a cust
5860: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 om xFileControl
5870: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 method should us
5880: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 e opcodes.** gre
5890: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f ater than 100 to
58a0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 avoid conflicts
58b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 ..**.** The xSec
58c0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 torSize() method
58d0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 returns the sec
58e0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a tor size of the.
58f0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 ** device that u
5900: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c nderlies the fil
5910: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 e. The sector s
5920: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 ize is the.** mi
5930: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 nimum write that
5940: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 can be performe
5950: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 d without distur
5960: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 bing.** other by
5970: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e tes in the file.
5980: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 The xDeviceCha
5990: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a racteristics().*
59a0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 * method returns
59b0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 a bit vector de
59c0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f scribing behavio
59d0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 rs of the.** und
59e0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a erlying device:.
59f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
5a00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
5a10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e _ATOMIC].** <li>
5a20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5a30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 TOMIC512].** <li
5a40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5a50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC1K].** <li
5a60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5a70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC2K].** <li
5a80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5a90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC4K].** <li
5aa0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5ab0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC8K].** <li
5ac0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5ad0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c ATOMIC16K].** <l
5ae0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
5af0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c _ATOMIC32K].** <
5b00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
5b10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 P_ATOMIC64K].**
5b20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
5b30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a AP_SAFE_APPEND].
5b40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
5b50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
5b60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
5b70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5b80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 P_ATOMIC propert
5b90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c y means that all
5ba0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e writes of.** an
5bb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 y size are atomi
5bc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
5bd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 OCAP_ATOMICnnn v
5be0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 alues.** mean th
5bf0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f at writes of blo
5c00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e cks that are nnn
5c10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
5c20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 nd.** are aligne
5c30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 d to an address
5c40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 which is an inte
5c50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a ger multiple of.
5c60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 ** nnn are atomi
5c70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
5c80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
5c90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 value means.**
5ca0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 that when data i
5cb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 s appended to a
5cc0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 file, the data i
5cd0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 s appended.** fi
5ce0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a rst then the siz
5cf0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 e of the file is
5d00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 extended, never
5d10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 the other.** wa
5d20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 y around. The S
5d30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
5d40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 ENTIAL property
5d50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e means that.** in
5d60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 formation is wri
5d70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 tten to disk in
5d80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 the same order a
5d90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 s calls.** to xW
5da0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 rite()..**.** If
5db0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 xRead() returns
5dc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5dd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 ORT_READ it must
5de0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e also fill.** in
5df0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 the unread port
5e00: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 ions of the buff
5e10: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 er with zeros.
5e20: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 A VFS that.** fa
5e30: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c ils to zero-fill
5e40: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 short reads mig
5e50: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e ht seem to work.
5e60: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 However,.** fa
5e70: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 ilure to zero-fi
5e80: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 ll short reads w
5e90: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c ill eventually l
5ea0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 ead to.** databa
5eb0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a se corruption..*
5ec0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
5ed0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
5ee0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ods sqlite3_io_m
5ef0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
5f00: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5f10: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
5f20: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f on;. int (*xClo
5f30: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 se)(sqlite3_file
5f40: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 *);. int (*xRea
5f50: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a d)(sqlite3_file*
5f60: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d , void*, int iAm
5f70: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
5f80: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
5f90: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 *xWrite)(sqlite3
5fa0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f _file*, const vo
5fb0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
5fc0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
5fd0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 st);. int (*xTr
5fe0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f uncate)(sqlite3_
5ff0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
6000: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e nt64 size);. in
6010: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 t (*xSync)(sqlit
6020: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c e3_file*, int fl
6030: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 ags);. int (*xF
6040: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 ileSize)(sqlite3
6050: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
6060: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 int64 *pSize);.
6070: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 int (*xLock)(sq
6080: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
6090: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f );. int (*xUnlo
60a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
60b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
60c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c *xCheckReservedL
60d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
60e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 e*, int *pResOut
60f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
6100: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 Control)(sqlite3
6110: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 _file*, int op,
6120: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 void *pArg);. i
6130: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 nt (*xSectorSize
6140: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 )(sqlite3_file*)
6150: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 ;. int (*xDevic
6160: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
6170: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 )(sqlite3_file*)
6180: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 ;. /* Additiona
6190: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 l methods may be
61a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
61b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a releases */.};.
61c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
61d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 Standard File C
61e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b ontrol Opcodes {
61f0: 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30 3e H11310} <S30800>
6200: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
6210: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 eger constants a
6220: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 re opcodes for t
6230: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
6240: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 method.** of the
6250: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6260: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 hods] object and
6270: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
6280: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
6290: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a ].** interface..
62a0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
62b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
62c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
62d0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e d for debugging.
62e0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
62f0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c causes the xFil
6300: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
6310: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 to write the cur
6320: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a rent state of.**
6330: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f the lock (one o
6340: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e f [SQLITE_LOCK_N
6350: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f ONE], [SQLITE_LO
6360: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b CK_SHARED],.** [
6370: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
6380: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c RVED], [SQLITE_L
6390: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
63a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
63b0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 CLUSIVE]).** int
63c0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 o an integer tha
63d0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d t the pArg argum
63e0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 ent points to. T
63f0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a his capability.*
6400: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 * is used during
6410: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c testing and onl
6420: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 y needs to be su
6430: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c pported when SQL
6440: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 ITE_TEST.** is d
6450: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 efined..*/.#defi
6460: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
6470: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 LOCKSTATE
6480: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
6490: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 E_GET_LOCKPROXYF
64a0: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 ILE 2.#defi
64b0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f ne SQLITE_SET_LO
64c0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
64d0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
64e0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 E_LAST_ERRNO
64f0: 20 20 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 4../*.*
6500: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
6510: 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 x Handle {H17110
6520: 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a } <S20130>.**.**
6530: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c The mutex modul
6540: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 e within SQLite
6550: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 defines [sqlite3
6560: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e _mutex] to be an
6570: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 .** abstract typ
6580: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 e for a mutex ob
6590: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 ject. The SQLit
65a0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f e core never loo
65b0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 ks.** at the int
65c0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 ernal representa
65d0: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 tion of an [sqli
65e0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 te3_mutex]. It
65f0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 only.** deals wi
6600: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 th pointers to t
6610: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
6620: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a x] object..**.**
6630: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 Mutexes are cre
6640: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
6650: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
6660: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
6670: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 truct sqlite3_mu
6680: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 tex sqlite3_mute
6690: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 x;../*.** CAPI3R
66a0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
66b0: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d Object {H11140}
66c0: 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20100>.**.**
66d0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
66e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
66f0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
6700: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
6710: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 een.** the SQLit
6720: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 e core and the u
6730: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 nderlying operat
6740: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ing system. The
6750: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 "vfs".** in the
6760: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a name of the obj
6770: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 ect stands for "
6780: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
6790: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tem"..**.** The
67a0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
67b0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
67c0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
67d0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
67e0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
67f0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
6800: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
6810: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
6820: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
6830: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
6840: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
6850: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
6860: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
6870: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
6880: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
6890: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
68a0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
68b0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
68c0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
68d0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
68e0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
68f0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
6900: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
6910: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
6920: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
6930: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
6940: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
6950: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
6960: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
6970: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
6980: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
6990: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
69a0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
69b0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
69c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
69d0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
69e0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
69f0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
6a00: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
6a10: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
6a20: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
6a30: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
6a40: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
6a50: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
6a60: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
6a70: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
6a80: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
6a90: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
6aa0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
6ab0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
6ac0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
6ad0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
6ae0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
6af0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
6b00: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
6b10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
6b20: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
6b30: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
6b40: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
6b50: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
6b60: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
6b70: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
6b80: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
6b90: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
6ba0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
6bb0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
6bc0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
6bd0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
6be0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
6bf0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
6c00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
6c10: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
6c20: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
6c30: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
6c40: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
6c50: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
6c60: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
6c70: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
6c80: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
6c90: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
6ca0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
6cb0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 s..**.** SQLite
6cc0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 will guarantee t
6cd0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d hat the zFilenam
6ce0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
6cf0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 Open.** is eithe
6d00: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
6d10: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 or string obtai
6d20: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c ned.** from xFul
6d30: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 lPathname(). SQ
6d40: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 Lite further gua
6d50: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 rantees that.**
6d60: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 the string will
6d70: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 be valid and unc
6d80: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c hanged until xCl
6d90: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c ose() is.** call
6da0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 ed. Because of t
6db0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
6dc0: 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 ense,.** the [sq
6dd0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 lite3_file] can
6de0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 safely store a p
6df0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
6e00: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 filename if it
6e10: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 needs to remembe
6e20: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 r the filename f
6e30: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a or some reason..
6e40: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e ** If the zFilen
6e50: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
6e60: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c xOpen is a NULL
6e70: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f pointer then xO
6e80: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 pen.** must invi
6e90: 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f te its own tempo
6ea0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 rary name for th
6eb0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 e file. Wheneve
6ec0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e r the .** xFilen
6ed0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
6ee0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c NULL it will al
6ef0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 so be the case t
6f00: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 hat the.** flags
6f10: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 parameter will
6f20: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f include [SQLITE_
6f30: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
6f40: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 SE]..**.** The f
6f50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
6f60: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 xOpen() include
6f70: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 s all bits set i
6f80: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 n.** the flags a
6f90: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
6fa0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 te3_open_v2()].
6fb0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f Or if [sqlite3_
6fc0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 open()].** or [s
6fd0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
6fe0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 is used, then f
6ff0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 lags includes at
7000: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 least.** [SQLIT
7010: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
7020: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
7030: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 _CREATE]. .** If
7040: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 xOpen() opens a
7050: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 file read-only
7060: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f then it sets *pO
7070: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e utFlags to.** in
7080: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
7090: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f EN_READONLY]. O
70a0: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f ther bits in *pO
70b0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 utFlags may be s
70c0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 et..**.** SQLite
70d0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
70e0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
70f0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
7100: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
7110: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
7120: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
7130: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
7140: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
7150: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
7160: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
7170: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
7180: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
7190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
71a0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
71b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
71c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
71d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
71e0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
71f0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
7200: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
7210: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
7220: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
7230: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a NAL].** </ul>.**
7240: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f .** The file I/O
7250: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
7260: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 can use the obje
7270: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f ct type flags to
7280: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 .** change the w
7290: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 ay it deals with
72a0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 files. For exa
72b0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 mple, an applica
72c0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 tion.** that doe
72d0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 s not care about
72e0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 crash recovery
72f0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 or rollback migh
7300: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 t make.** the op
7310: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 en of a journal
7320: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 file a no-op. W
7330: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f rites to this jo
7340: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 urnal would.** a
7350: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 lso be no-ops, a
7360: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 nd any attempt t
7370: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e o read the journ
7380: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a al would return.
7390: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e ** SQLITE_IOERR.
73a0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 Or the impleme
73b0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ntation might re
73c0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 cognize that a d
73d0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
73e0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 will be doing pa
73f0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f ge-aligned secto
7400: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 r reads and writ
7410: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a es in a random.*
7420: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 * order and set
7430: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 up its I/O subsy
7440: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 stem accordingly
7450: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d ..**.** SQLite m
7460: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e ight also add on
7470: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
7480: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
7490: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a xOpen method:.**
74a0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
74b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
74c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
74d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
74e0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 N_EXCLUSIVE].**
74f0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
7500: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
7510: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 ETEONCLOSE] flag
7520: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 means the file
7530: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c should be.** del
7540: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 eted when it is
7550: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51 closed. The [SQ
7560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
7570: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c ONCLOSE].** will
7580: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 be set for TEMP
7590: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 databases, jou
75a0: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 rnals and for su
75b0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
75c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
75d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 N_EXCLUSIVE] fla
75e0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 g means the file
75f0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 should be opene
7600: 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 d.** for exclusi
7610: 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 ve access. This
7620: 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 flag is set for
7630: 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 all files excep
7640: 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 t.** for the mai
7650: 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e n database file.
7660: 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 .**.** At least
7670: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f szOsFile bytes o
7680: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c f memory are all
7690: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 ocated by SQLite
76a0: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 .** to hold the
76b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
76c0: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 structure passed
76d0: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a as the third.**
76e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
76f0: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d en. The xOpen m
7700: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 ethod does not h
7710: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 ave to.** alloca
7720: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 te the structure
7730: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 ; it should just
7740: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a fill it in..**.
7750: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
7760: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 ument to xAccess
7770: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 () may be [SQLIT
7780: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d E_ACCESS_EXISTS]
7790: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 .** to test for
77a0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 the existence of
77b0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c a file, or [SQL
77c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
77d0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 RITE] to.** test
77e0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
77f0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 is readable and
7800: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 writable, or [SQ
7810: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
7820: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 ].** to test whe
7830: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 ther a file is a
7840: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 t least readable
7850: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e . The file can
7860: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f be a.** directo
7870: 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ry..**.** SQLite
7880: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c will always all
7890: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d ocate at least m
78a0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 xPathname+1 byte
78b0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 s for the.** out
78c0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c put buffer xFull
78d0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 Pathname. The e
78e0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 xact size of the
78f0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
7900: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 * is also passed
7910: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 as a parameter
7920: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 to both methods
7930: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 . If the output
7940: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 buffer.** is not
7950: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b large enough, [
7960: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
7970: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
7980: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 ned. Since this
7990: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 is.** handled as
79a0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 a fatal error b
79b0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d y SQLite, vfs im
79c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
79d0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a ould endeavor.**
79e0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 to prevent this
79f0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 by setting mxPa
7a00: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 thname to a suff
7a10: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 iciently large v
7a20: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
7a30: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 xRandomness(), x
7a40: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 Sleep(), and xCu
7a50: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 rrentTime() inte
7a60: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f rfaces.** are no
7a70: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 t strictly a par
7a80: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 t of the filesys
7a90: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 tem, but they ar
7aa0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e e.** included in
7ab0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 the VFS structu
7ac0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e re for completen
7ad0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e ess..** The xRan
7ae0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 domness() functi
7af0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 on attempts to r
7b00: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 eturn nBytes byt
7b10: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 es.** of good-qu
7b20: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 ality randomness
7b30: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 into zOut. The
7b40: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 return value is
7b50: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e .** the actual n
7b60: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
7b70: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 f randomness obt
7b80: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 ained..** The xS
7b90: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 leep() method ca
7ba0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 uses the calling
7bb0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 thread to sleep
7bc0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 for at.** least
7bd0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d the number of m
7be0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 icroseconds give
7bf0: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 n. The xCurrent
7c00: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 Time().** method
7c10: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 returns a Julia
7c20: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 n Day Number for
7c30: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 the current dat
7c40: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a e and time..**.*
7c50: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
7c60: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c sqlite3_vfs sql
7c70: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 ite3_vfs;.struct
7c80: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 sqlite3_vfs {.
7c90: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 int iVersion;
7ca0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 /* Str
7cb0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e ucture version n
7cc0: 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 umber */. int s
7cd0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 zOsFile;
7ce0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 /* Size of s
7cf0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 ubclassed sqlite
7d00: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 3_file */. int
7d10: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 mxPathname;
7d20: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
7d30: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 file pathname le
7d40: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 ngth */. sqlite
7d50: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 3_vfs *pNext;
7d60: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 /* Next regis
7d70: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 tered VFS */. c
7d80: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
7d90: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ; /* Name
7da0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 of this virtual
7db0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 file system */.
7dc0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
7dd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 /* Poi
7de0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 nter to applicat
7df0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 ion-specific dat
7e00: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 a */. int (*xOp
7e10: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
7e20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
7e30: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c ame, sqlite3_fil
7e40: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 e*,.
7e50: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e int flags, in
7e60: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 t *pOutFlags);.
7e70: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 int (*xDelete)(
7e80: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
7e90: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
7ea0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 int syncDir);.
7eb0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 int (*xAccess)(
7ec0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
7ed0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
7ee0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
7ef0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
7f00: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 (*xFullPathname
7f10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
7f20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
7f30: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 e, int nOut, cha
7f40: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 r *zOut);. void
7f50: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c *(*xDlOpen)(sql
7f60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
7f70: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
7f80: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 );. void (*xDlE
7f90: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
7fa0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
7fb0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 har *zErrMsg);.
7fc0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d void (*(*xDlSym
7fd0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 )(sqlite3_vfs*,v
7fe0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 oid*, const char
7ff0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 *zSymbol))(void
8000: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 );. void (*xDlC
8010: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lose)(sqlite3_vf
8020: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e s*, void*);. in
8030: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 t (*xRandomness)
8040: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
8050: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
8060: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 zOut);. int (*x
8070: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 Sleep)(sqlite3_v
8080: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 fs*, int microse
8090: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a conds);. int (*
80a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 xCurrentTime)(sq
80b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 lite3_vfs*, doub
80c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 le*);. int (*xG
80d0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c etLastError)(sql
80e0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 ite3_vfs*, int,
80f0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 char *);. /* Ne
8100: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 w fields may be
8110: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 appended in figu
8120: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 re versions. Th
8130: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 e iVersion. **
8140: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 value will incre
8150: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 ment whenever th
8160: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d is happens. */.}
8170: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
8180: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
8190: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 xAccess VFS met
81a0: 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 hod {H11190} <H1
81b0: 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 1140>.**.** Thes
81c0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
81d0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
81e0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
81f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
8200: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
8210: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
8220: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 fs] object. {END
8230: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e } They determin
8240: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f e.** what kind o
8250: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 f permissions th
8260: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
8270: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e is looking for.
8280: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
8290: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 ACCESS_EXISTS, t
82a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
82b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 d.** simply chec
82c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
82d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 ile exists..** W
82e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
82f0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 S_READWRITE, the
8300: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
8310: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
8320: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f r the file is bo
8330: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 th readable and
8340: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 writable..** Wit
8350: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
8360: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
8370: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
8380: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
8390: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
83a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
83b0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
83c0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
83d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
83e0: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 WRITE 1.#define
83f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
8400: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a AD 2../*.**
8410: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 CAPI3REF: Initi
8420: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 alize The SQLite
8430: 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 Library {H10130
8440: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 } <S20000><S3010
8450: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
8460: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
8470: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 ) routine initia
8480: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c lizes the.** SQL
8490: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
84a0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
84b0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 wn() routine.**
84c0: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 deallocates any
84d0: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 resources that w
84e0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ere allocated by
84f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
8500: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 ize()..**.** A c
8510: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
8520: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 nitialize() is a
8530: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 n "effective" ca
8540: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 ll if it is.** t
8550: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 he first time sq
8560: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8570: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 () is invoked du
8580: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d ring the lifetim
8590: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 e of.** the proc
85a0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 ess, or if it is
85b0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
85c0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
85d0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a ze() is invoked.
85e0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 ** following a c
85f0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
8600: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 hutdown(). Only
8610: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
8620: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 ll.** of sqlite3
8630: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f _initialize() do
8640: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a es any initializ
8650: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 ation. All othe
8660: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 r calls.** are h
8670: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a armless no-ops..
8680: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 **.** Among othe
8690: 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 r things, sqlite
86a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 3_initialize() s
86b0: 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 hall invoke.** s
86c0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
86d0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 . Similarly, sq
86e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
86f0: 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 .** shall invoke
8700: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
8710: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
8720: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
8730: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
8740: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e s [SQLITE_OK] on
8750: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 success..** If
8760: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c for some reason,
8770: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
8780: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 ize() is unable
8790: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a to initialize.**
87a0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 the library (pe
87b0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 rhaps it is unab
87c0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 le to allocate a
87d0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 needed resource
87e0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 such.** as a mu
87f0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 tex) it returns
8800: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
8810: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
8820: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 TE_OK]..**.** Th
8830: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
8840: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
8850: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 s called interna
8860: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 lly by many othe
8870: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
8880: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 rfaces so that a
8890: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 n application us
88a0: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e ually does not n
88b0: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 eed to.** invoke
88c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
88d0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 ize() directly.
88e0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 For example, [s
88f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
8900: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f * calls sqlite3_
8910: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 initialize() so
8920: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
8930: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d ry will be autom
8940: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 atically.** init
8950: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 ialized when [sq
8960: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 lite3_open()] is
8970: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 called if it ha
8980: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c s not be initial
8990: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e ized.** already.
89a0: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 However, if SQ
89b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
89c0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 with the [SQLIT
89d0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d E_OMIT_AUTOINIT]
89e0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
89f0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 option, then th
8a00: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c e automatic call
8a10: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 s to sqlite3_ini
8a20: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 tialize().** are
8a30: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 omitted and the
8a40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
8a50: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 t call sqlite3_i
8a60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
8a70: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f ctly.** prior to
8a80: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
8a90: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
8aa0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 e. For maximum
8ab0: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 portability,.**
8ac0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
8ad0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
8ae0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b ons always invok
8af0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
8b00: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 lize().** direct
8b10: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e ly prior to usin
8b20: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 g any other SQLi
8b30: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 te interface. F
8b40: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a uture releases.*
8b50: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 * of SQLite may
8b60: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 require this. I
8b70: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
8b80: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 he behavior exhi
8b90: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 bited.** when SQ
8ba0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
8bb0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d with [SQLITE_OM
8bc0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 IT_AUTOINIT] mig
8bd0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a ht become the.**
8be0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
8bf0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 r in some future
8c00: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
8c10: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te..**.** The sq
8c20: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
8c30: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 routine does ope
8c40: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
8c50: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 ecific.** initia
8c60: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 lization of the
8c70: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
8c80: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
8c90: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 end().** routine
8ca0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
8cb0: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 ct of sqlite3_os
8cc0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 _init(). Typica
8cd0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f l tasks.** perfo
8ce0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f rmed by these ro
8cf0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 utines include a
8d00: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 llocation or dea
8d10: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
8d20: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 static resources
8d30: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e , initialization
8d40: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 of global varia
8d50: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 bles,.** setting
8d60: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 up a default [s
8d70: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 qlite3_vfs] modu
8d80: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 le, or setting u
8d90: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 p.** a default c
8da0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 onfiguration usi
8db0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ng [sqlite3_conf
8dc0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ig()]..**.** The
8dd0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
8de0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 uld never invoke
8df0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f either sqlite3_
8e00: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 os_init().** or
8e10: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
8e20: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 directly. The
8e30: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
8e40: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a ld only invoke.*
8e50: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 * sqlite3_initia
8e60: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lize() and sqlit
8e70: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
8e80: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
8e90: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 nit().** interfa
8ea0: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 ce is called aut
8eb0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 omatically by sq
8ec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8ed0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 () and.** sqlite
8ee0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 3_os_end() is ca
8ef0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f lled by sqlite3_
8f00: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 shutdown(). App
8f10: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c ropriate.** impl
8f20: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 ementations for
8f30: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
8f40: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
8f50: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 _end().** are bu
8f60: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 ilt into SQLite
8f70: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 when it is compi
8f80: 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 led for unix, wi
8f90: 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a ndows, or os/2..
8fa0: 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f ** When built fo
8fb0: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
8fc0: 73 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 s (using the [SQ
8fd0: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d LITE_OS_OTHER=1]
8fe0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a compile-time.**
8ff0: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 option) the app
9000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 lication must su
9010: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 pply a suitable
9020: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 implementation f
9030: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 or.** sqlite3_os
9040: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
9050: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 te3_os_end(). A
9060: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 n application-su
9070: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d pplied.** implem
9080: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 entation of sqli
9090: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 te3_os_init() or
90a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
90b0: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e ).** must return
90c0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
90d0: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 success and some
90e0: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f other [error co
90f0: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c de] upon.** fail
9100: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ure..*/.int sqli
9110: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 te3_initialize(v
9120: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
9130: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3_shutdown(void)
9140: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 ;.int sqlite3_os
9150: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 _init(void);.int
9160: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
9170: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
9180: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
9190: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c ing The SQLite L
91a0: 69 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20 ibrary {H14100}
91b0: 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e <S20000><S30200>
91c0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
91d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
91e0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
91f0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
9200: 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e make global con
9210: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
9220: 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 anges to SQLite
9230: 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 in order to tune
9240: 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 SQLite to the s
9250: 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 pecific needs of
9260: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
9270: 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c ion. The defaul
9280: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 t configuration
9290: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
92a0: 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 or most.** appli
92b0: 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 cations and so t
92c0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
92d0: 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 sually not neces
92e0: 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 sary. It is.**
92f0: 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 provided to supp
9300: 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 ort rare applica
9310: 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 tions with unusu
9320: 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 al needs..**.**
9330: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
9340: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
9350: 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 s not threadsafe
9360: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
9370: 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 on.** must insur
9380: 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 e that no other
9390: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
93a0: 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 s are invoked by
93b0: 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 other.** thread
93c0: 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f s while sqlite3_
93d0: 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e config() is runn
93e0: 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 ing. Furthermor
93f0: 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e, sqlite3_confi
9400: 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 g().** may only
9410: 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 be invoked prior
9420: 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 to library init
9430: 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 ialization using
9440: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 .** [sqlite3_ini
9450: 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 tialize()] or af
9460: 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 ter shutdown by
9470: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
9480: 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 n()]..** Note, h
9490: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c owever, that sql
94a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 ite3_config() ca
94b0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 n be called as p
94c0: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d art of the.** im
94d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
94e0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
94f0: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f efined [sqlite3_
9500: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a os_init()]..**.*
9510: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
9520: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
9530: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 config() is an i
9540: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 nteger.** [SQLIT
9550: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
9560: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 HREAD | configur
9570: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 ation option] th
9580: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a at determines.**
9590: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f what property o
95a0: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 f SQLite is to b
95b0: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 e configured. S
95c0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
95d0: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 nts.** vary depe
95e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 nding on the [SQ
95f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
9600: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 LETHREAD | confi
9610: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
9620: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
9630: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
9640: 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 When a configur
9650: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
9660: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e set, sqlite3_con
9670: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 fig() returns [S
9680: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 QLITE_OK]..** If
9690: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 the option is u
96a0: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 nknown or SQLite
96b0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 is unable to se
96c0: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 t the option.**
96d0: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
96e0: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d e returns a non-
96f0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
9700: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
9710: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31 30 ments:.** [H1410
9720: 33 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 31 34 3] [H14106] [H14
9730: 31 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b 48 120] [H14123] [H
9740: 31 34 31 32 36 5d 20 5b 48 31 34 31 32 39 5d 20 14126] [H14129]
9750: 5b 48 31 34 31 33 32 5d 20 5b 48 31 34 31 33 35 [H14132] [H14135
9760: 5d 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b 48 ].** [H14138] [H
9770: 31 34 31 34 31 5d 20 5b 48 31 34 31 34 34 5d 20 14141] [H14144]
9780: 5b 48 31 34 31 34 37 5d 20 5b 48 31 34 31 35 30 [H14147] [H14150
9790: 5d 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 34 31 ] [H14153] [H141
97a0: 35 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a 20 56] [H14159].**
97b0: 5b 48 31 34 31 36 32 5d 20 5b 48 31 34 31 36 35 [H14162] [H14165
97c0: 5d 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53 51 ] [H14168].*/.SQ
97d0: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
97e0: 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f L int sqlite3_co
97f0: 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a nfig(int, ...);.
9800: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
9810: 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 Configure datab
9820: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
9830: 20 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 {H14200} <S2000
9840: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
9850: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c AL.**.** The sql
9860: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
9870: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
9880: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
9890: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
98a0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
98b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
98c0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
98d0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
98e0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
98f0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
9900: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
9910: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
9920: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
9930: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
9940: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
9950: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a gument). The.**
9960: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
9970: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 ig() interface c
9980: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 an only be used
9990: 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 immediately afte
99a0: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 r.** the databas
99b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
99c0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
99d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a qlite3_open()],.
99e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
99f0: 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 16()], or [sqlit
9a00: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 e3_open_v2()].
9a10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
9a20: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
9a30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
9a40: 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 D,V,...) is the
9a50: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
9a60: 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 n verb - an inte
9a70: 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e ger code that in
9a80: 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 dicates what.**
9a90: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 aspect of the [d
9aa0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
9ab0: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e on] is being con
9ac0: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 figured..** The
9ad0: 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 only choice for
9ae0: 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 this value is [S
9af0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
9b00: 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 OOKASIDE]..** Ne
9b10: 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 w verbs are like
9b20: 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 ly to be added i
9b30: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
9b40: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
9b50: 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d Additional argum
9b60: 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 ents depend on t
9b70: 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 he verb..**.** R
9b80: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
9b90: 5b 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 [H14203] [H14206
9ba0: 5d 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 ] [H14209] [H142
9bb0: 31 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 12] [H14215].*/.
9bc0: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
9bd0: 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
9be0: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 db_config(sqlite
9bf0: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3*, int op, ...)
9c00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
9c10: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
9c20: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 tion Routines {H
9c30: 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 10155} <S20120>.
9c40: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
9c50: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
9c60: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
9c70: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
9c80: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 erface between S
9c90: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 QLite.** and low
9ca0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
9cb0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
9cc0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 s..**.** This ob
9cd0: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 ject is used in
9ce0: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 only one place i
9cf0: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
9d00: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 erface..** A poi
9d10: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
9d20: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
9d30: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 ct is the argume
9d40: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 nt to.** [sqlite
9d50: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 3_config()] when
9d60: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
9d70: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 on option is.**
9d80: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
9d90: 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 ALLOC]. By crea
9da0: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 ting an instance
9db0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a of this object.
9dc0: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 ** and passing i
9dd0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
9de0: 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 nfig()] during c
9df0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e onfiguration, an
9e00: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
9e10: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 can specify an a
9e20: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 lternative memor
9e30: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 y allocation sub
9e40: 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 system.** for SQ
9e50: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 Lite to use for
9e60: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
9e70: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e ic memory needs.
9e80: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
9e90: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 SQLite comes wi
9ea0: 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 th a built-in me
9eb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 mory allocator t
9ec0: 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 hat is.** perfec
9ed0: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 tly adequate for
9ee0: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e the overwhelmin
9ef0: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 g majority of ap
9f00: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e plications.** an
9f10: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 d that this obje
9f20: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 ct is only usefu
9f30: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f l to a tiny mino
9f40: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 rity of applicat
9f50: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 ions.** with spe
9f60: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 cialized memory
9f70: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 allocation requi
9f80: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f rements. This o
9f90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f bject is.** also
9fa0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 used during tes
9fb0: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 ting of SQLite i
9fc0: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 n order to speci
9fd0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
9fe0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
9ff0: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c cator that simul
a000: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d ates memory out-
a010: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 of-memory condit
a020: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 ions in.** order
a030: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 to verify that
a040: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 SQLite recovers
a050: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 gracefully from
a060: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f such.** conditio
a070: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d ns..**.** The xM
a080: 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e alloc, xFree, an
a090: 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f d xRealloc metho
a0a0: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b ds must work lik
a0b0: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 e the.** malloc(
a0c0: 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 ), free(), and r
a0d0: 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f ealloc() functio
a0e0: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ns from the stan
a0f0: 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a dard library..**
a100: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 .** xSize should
a110: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f return the allo
a120: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 cated size of a
a130: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
a140: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 n.** previously
a150: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d obtained from xM
a160: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f alloc or xReallo
a170: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 c. The allocate
a180: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 d size.** is alw
a190: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 ays at least as
a1a0: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 big as the reque
a1b0: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 sted size but ma
a1c0: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a y be larger..**.
a1d0: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 ** The xRoundup
a1e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 method returns w
a1f0: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 hat would be the
a200: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 allocated size
a210: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 of.** a memory a
a220: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 llocation given
a230: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 a particular req
a240: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f uested size. Mo
a250: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c st memory.** all
a260: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
a270: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
a280: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 ons at least to
a290: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c the next multipl
a2a0: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 e.** of 8. Some
a2b0: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
a2c0: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 d up to a larger
a2d0: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 multiple or to
a2e0: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a a power of 2..**
a2f0: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 .** The xInit me
a300: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 thod initializes
a310: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
a320: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 cator. (For exa
a330: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 mple,.** it migh
a340: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 t allocate any r
a350: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f equire mutexes o
a360: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 r initialize int
a370: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 ernal data.** st
a380: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 ructures. The x
a390: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
a3a0: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 is invoked (indi
a3b0: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 rectly) by.** [s
a3c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
a3d0: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 )] and should de
a3e0: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 allocate any res
a3f0: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a ources acquired.
a400: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 ** by xInit. Th
a410: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 e pAppData point
a420: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 er is used as th
a430: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
a440: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 to.** xInit and
a450: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 xShutdown..*/.t
a460: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
a470: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
a480: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 s sqlite3_mem_me
a490: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
a4a0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
a4b0: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d s {. void *(*xM
a4c0: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 alloc)(int);
a4d0: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 /* Memory a
a4e0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 llocation functi
a4f0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 on */. void (*x
a500: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Free)(void*);
a510: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 /* Free a
a520: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
a530: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 n */. void *(*x
a540: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 Realloc)(void*,i
a550: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 nt); /* Resize
a560: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f an allocation */
a570: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 . int (*xSize)(
a580: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
a590: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 /* Return the
a5a0: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 size of an alloc
a5b0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 ation */. int (
a5c0: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b *xRoundup)(int);
a5d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 /* Rou
a5e0: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 nd up request si
a5f0: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e ze to allocation
a600: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 size */. int (
a610: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 *xInit)(void*);
a620: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 /* Ini
a630: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
a640: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
a650: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f void (*xShutdo
a660: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 wn)(void*);
a670: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 /* Deinitialize
a680: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
a690: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
a6a0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
a6b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
a6c0: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 ument to xInit()
a6d0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 and xShutdown()
a6e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
a6f0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
a700: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 ation Options {H
a710: 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 10160} <S20000>.
a720: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
a730: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
a740: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
a750: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
a760: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
a770: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
a780: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
a790: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
a7a0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
a7b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
a7c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
a7d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
a7e0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
a7f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
a800: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
a810: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
a820: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
a830: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
a840: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
a850: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
a860: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
a870: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
a880: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
a890: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
a8a0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
a8b0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
a8c0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
a8d0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
a8e0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
a8f0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
a900: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
a910: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
a920: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
a930: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
a940: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
a950: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
a960: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
a970: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
a980: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
a990: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
a9a0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f ion. This optio
a9b0: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c n disables.** al
a9c0: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 l mutexing and p
a9d0: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 uts SQLite into
a9e0: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 a mode where it
a9f0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 can only be used
aa00: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 .** by a single
aa10: 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a thread.</dd>.**.
aa20: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
aa30: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
aa40: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
aa50: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
aa60: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
aa70: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e on. This option
aa80: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 disables.** mut
aa90: 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 exing on [databa
aaa0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
aab0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
aac0: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e tement] objects.
aad0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
aae0: 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ion is responsib
aaf0: 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 le for serializi
ab00: 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 ng access to.**
ab10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
ab20: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
ab30: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
ab40: 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 . But other mut
ab50: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
ab60: 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 led so that SQLi
ab70: 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 te will be safe
ab80: 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 to use in a mult
ab90: 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e i-threaded.** en
aba0: 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e vironment as lon
abb0: 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 g as no two thre
abc0: 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 ads attempt to u
abd0: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b se the same.** [
abe0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
abf0: 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 ion] at the same
ac00: 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 time. See the
ac10: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
ac20: 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f .** documentatio
ac30: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
ac40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 information.</d
ac50: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
ac60: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
ac70: 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 LIZED</dt>.** <d
ac80: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
ac90: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
aca0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f option. This o
acb0: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a ption enables.**
acc0: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 all mutexes inc
acd0: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 luding the recur
ace0: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 sive.** mutexes
acf0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
ad00: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
ad10: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
ad20: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e ] objects..** In
ad30: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 this mode (whic
ad40: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 h is the default
ad50: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
ad60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
ad70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
ad80: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 AFE=1]) the SQLi
ad90: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 te library will
ada0: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 itself serialize
adb0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 access.** to [d
adc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
add0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
ade0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 ed statements] s
adf0: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 o that the.** ap
ae00: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 plication is fre
ae10: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d e to use the sam
ae20: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
ae30: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a ection] or the.*
ae40: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 * same [prepared
ae50: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 statement] in d
ae60: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 ifferent threads
ae70: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
ae80: 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 e..** See the [t
ae90: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 hreading mode] d
aea0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
aeb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
aec0: 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a rmation.</dd>.**
aed0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
aee0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 ONFIG_MALLOC</dt
aef0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
af00: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
af10: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
af20: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
af30: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 to an.** instanc
af40: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
af50: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
af60: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 tructure. The a
af70: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
af80: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 s.** alternative
af90: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
afa0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
afb0: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 tines to be used
afc0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 in place of.**
afd0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
afe0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 ation routines b
aff0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
b000: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
b010: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
b020: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a ETMALLOC</dt>.**
b030: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
b040: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
b050: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
b060: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
b070: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
b080: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
b090: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
b0a0: 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 ture. The [sqli
b0b0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
b0c0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
b0d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
b0e0: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
b0f0: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
b100: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a tion routines..*
b110: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
b120: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
b130: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
b140: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
b150: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
b160: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 with a wrapper t
b170: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 hat simulations
b180: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b190: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 n failure or.**
b1a0: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 tracks memory us
b1b0: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 age, for example
b1c0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
b1d0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
b1e0: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a EMSTATUS</dt>.**
b1f0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
b200: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 takes single ar
b210: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 gument of type i
b220: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 nt, interpreted
b230: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e as a .** boolean
b240: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 , which enables
b250: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 or disables the
b260: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 collection of me
b270: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
b280: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 .** statistics.
b290: 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 When disabled, t
b2a0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c he following SQL
b2b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 ite interfaces b
b2c0: 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 ecome .** non-op
b2d0: 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 erational:.**
b2e0: 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b <ul>.** <li> [
b2f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
b300: 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e sed()].** <li>
b310: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
b320: 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a _highwater()].**
b330: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
b340: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
b350: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
b360: 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
b370: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c .** </ul>.** <
b380: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
b390: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
b3a0: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATCH</dt>.** <dd
b3b0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 >This option spe
b3c0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
b3d0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
b3e0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
b3f0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 e for.** scratch
b400: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 memory. There
b410: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
b420: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 nts: A pointer
b430: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 to the memory, t
b440: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
b450: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 ch scratch buffe
b460: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 r (sz), and the
b470: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 number of buffer
b480: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a s (N). The sz.*
b490: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 * argument must
b4a0: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 be a multiple of
b4b0: 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 16. The sz para
b4c0: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 meter should be
b4d0: 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c a few bytes.** l
b4e0: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 arger than the a
b4f0: 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 ctual scratch sp
b500: 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 ace required due
b510: 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 internal overhe
b520: 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ad..** The first
b530: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f .** argument sho
b540: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 uld point to an
b550: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 allocation of at
b560: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 least sz*N byte
b570: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 s of memory..**
b580: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
b590: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 no more than one
b5a0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 scratch buffer
b5b0: 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 at once per thre
b5c0: 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 ad, so.** N shou
b5d0: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 ld be set to the
b5e0: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 expected maximu
b5f0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 m number of thre
b600: 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 ads. The sz.**
b610: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 parameter should
b620: 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 be 6 times the
b630: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 size of the larg
b640: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 est database pag
b650: 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 e size..** Scrat
b660: 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 ch buffers are u
b670: 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 sed as part of t
b680: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 he btree balance
b690: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a operation. If.
b6a0: 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c ** The btree bal
b6b0: 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 ancer needs addi
b6c0: 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 tional memory be
b6d0: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f yond what is pro
b6e0: 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 vided by.** scra
b6f0: 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 tch buffers or i
b700: 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 f no scratch buf
b710: 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 fer space is spe
b720: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c cified, then SQL
b730: 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b ite.** goes to [
b740: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
b750: 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 ] to obtain the
b760: 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e memory it needs.
b770: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
b780: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
b790: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 GECACHE</dt>.**
b7a0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
b7b0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
b7c0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
b7d0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
b7e0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 use for.** the
b7f0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 database page ca
b800: 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 che with the def
b810: 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 ault page cache
b820: 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 implemenation.
b830: 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 .** This configu
b840: 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f ration should no
b850: 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 t be used if an
b860: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
b870: 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 ne page.** cache
b880: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
b890: 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 is loaded using
b8a0: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
b8b0: 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e G_PCACHE option.
b8c0: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 .** There are th
b8d0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ree arguments to
b8e0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 this option: A
b8f0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
b900: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 * memory, the si
b910: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 ze of each page
b920: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 buffer (sz), and
b930: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
b940: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 ages (N)..** The
b950: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 sz argument mus
b960: 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 t be a power of
b970: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 two between 512
b980: 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 and 32768. The
b990: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e first.** argumen
b9a0: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 t should point t
b9b0: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 o an allocation
b9c0: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
b9d0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
b9e0: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c ..** SQLite will
b9f0: 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 use the memory
ba00: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 provided by the
ba10: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
ba20: 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a o satisfy its.**
ba30: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f memory needs fo
ba40: 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 r the first N pa
ba50: 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 ges that it adds
ba60: 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 to cache. If a
ba70: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 dditional.** pag
ba80: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 e cache memory i
ba90: 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 s needed beyond
baa0: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
bab0: 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c by this option,
bac0: 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
bad0: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 goes to [sqlite3
bae0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 _malloc()] for t
baf0: 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 he additional st
bb00: 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 orage space..**
bb10: 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
bb20: 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 on might use one
bb30: 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 or more of the
bb40: 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c N buffers to hol
bb50: 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 d .** memory acc
bb60: 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 ounting informat
bb70: 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ion. </dd>.**.**
bb80: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
bb90: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 IG_HEAP</dt>.**
bba0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
bbb0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
bbc0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
bbd0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
bbe0: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c l use.** for all
bbf0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 of its dynamic
bc00: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
bc10: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 n needs beyond t
bc20: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a hose provided.**
bc30: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f for by [SQLITE_
bc40: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 CONFIG_SCRATCH]
bc50: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 and [SQLITE_CONF
bc60: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
bc70: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
bc80: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 e arguments: A p
bc90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
bca0: 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 mory, the number
bcb0: 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 of.** bytes in
bcc0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 the memory buffe
bcd0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d r, and the minim
bce0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
bcf0: 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 ze. If.** the f
bd00: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 irst pointer (th
bd10: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 e memory pointer
bd20: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 ) is NULL, then
bd30: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a SQLite reverts.*
bd40: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 * to using its d
bd50: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
bd60: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 locator (the sys
bd70: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 tem malloc() imp
bd80: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a lementation),.**
bd90: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 undoing any pri
bda0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 or invocation of
bdb0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
bdc0: 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 MALLOC]. If the
bdd0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 .** memory point
bde0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 er is not NULL a
bdf0: 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 nd either [SQLIT
be00: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 E_ENABLE_MEMSYS3
be10: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
be20: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 ENABLE_MEMSYS5]
be30: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 are defined, the
be40: 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 n the alternativ
be50: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
be60: 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 cator is engaged
be70: 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f to handle all o
be80: 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 f SQLites memory
be90: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
bea0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
beb0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
bec0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
bed0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
bee0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
bef0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
bf00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
bf10: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
bf20: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
bf30: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
bf40: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
bf50: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
bf60: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
bf70: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 level mutex rout
bf80: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
bf90: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 in place.** the
bfa0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 mutex routines b
bfb0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
bfc0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
bfd0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
bfe0: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
bff0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
c000: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
c010: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
c020: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
c030: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
c040: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
c050: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
c060: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b cture. The.** [
c070: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
c080: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
c090: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
c0a0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
c0b0: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 defined mutex r
c0c0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 outines..** This
c0d0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
c0e0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
c0f0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
c100: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 x allocation.**
c110: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
c120: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 wrapper used to
c130: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 track mutex usag
c140: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 e for performanc
c150: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f e.** profiling o
c160: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 r testing, for e
c170: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a xample.</dd>.**.
c180: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
c190: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
c1a0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
c1b0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f option takes two
c1c0: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
c1d0: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 determine the de
c1e0: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 fault.** memory
c1f0: 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 allcation lookas
c200: 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ide optimization
c210: 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 . The first arg
c220: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
c230: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f size of each loo
c240: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c kaside buffer sl
c250: 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ot and the secon
c260: 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
c270: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f of.** slots allo
c280: 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 cated to each da
c290: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c2a0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
c2b0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
c2c0: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c PCACHE</dt>.** <
c2d0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
c2e0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
c2f0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
c300: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
c310: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
c320: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 he_methods] obje
c330: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ct. This object
c340: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 specifies the i
c350: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 nterface.** to a
c360: 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 custom page cac
c370: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
c380: 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 n. SQLite makes
c390: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
c3a0: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 * object and use
c3b0: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 s it for page ca
c3c0: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 che memory alloc
c3d0: 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a ations.</dd>.**.
c3e0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
c3f0: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f NFIG_GETPCACHE</
c400: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
c410: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
c420: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
c430: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
c440: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 r to an.** [sqli
c450: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
c460: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c ds] object. SQL
c470: 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 ite copies of th
c480: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 e current.** pag
c490: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
c4a0: 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 tation into that
c4b0: 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a object.</dd>.**
c4c0: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
c4d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
c4e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
c4f0: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 1 /* nil */.#d
c500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
c510: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
c520: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 2 /* nil */.#
c530: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c540: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 NFIG_SERIALIZED
c550: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 3 /* nil */.
c560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
c570: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 ONFIG_MALLOC
c580: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 4 /* sqlite
c590: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
c5a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
c5b0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
c5c0: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 C 5 /* sqli
c5d0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a te3_mem_methods*
c5e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
c5f0: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
c600: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f H 6 /* vo
c610: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
c620: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
c630: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
c640: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 CACHE 7 /*
c650: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 void*, int sz, i
c660: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nt N */.#define
c670: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
c680: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f AP 8 /
c690: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 * void*, int nBy
c6a0: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 te, int min */.#
c6b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c6c0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 NFIG_MEMSTATUS
c6d0: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 9 /* boolean
c6e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
c6f0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
c700: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 10 /* sq
c710: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
c720: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
c730: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
c740: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f TMUTEX 11 /
c750: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
c760: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 methods* */./* p
c770: 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 reviously SQLITE
c780: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c _CONFIG_CHUNKALL
c790: 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e OC 12 which is n
c7a0: 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 ow unused. */ .#
c7b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c7c0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 NFIG_LOOKASIDE
c7d0: 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 13 /* int int
c7e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
c7f0: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
c800: 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 14 /* sq
c810: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
c820: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
c830: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
c840: 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 ETPCACHE 15
c850: 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
c860: 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f e_methods* */../
c870: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
c880: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
c890: 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 ions {H10170} <S
c8a0: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20000>.** EXPERI
c8b0: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
c8c0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
c8d0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
c8e0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
c8f0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
c900: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
c910: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
c920: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
c930: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
c940: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
c950: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
c960: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
c970: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
c980: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
c990: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
c9a0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
c9b0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
c9c0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
c9d0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
c9e0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
c9f0: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
ca00: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
ca10: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 3_db_config()] t
ca20: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
ca30: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
ca40: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ked. The [sqlit
ca50: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
ca60: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 interface will r
ca70: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a eturn a.** non-z
ca80: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
ca90: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
caa0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
cab0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 d configuration
cac0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 option.** is inv
cad0: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e oked..**.** <dl>
cae0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
caf0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
cb00: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
cb10: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
cb20: 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c three additional
cb30: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
cb40: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a determine the .*
cb50: 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d * [lookaside mem
cb60: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 ory allocator] c
cb70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 onfiguration for
cb80: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
cb90: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 onnection]..** T
cba0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
cbb0: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 t (the third par
cbc0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
cbd0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
cbe0: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
cbf0: 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 to a memory buff
cc00: 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f er to use for lo
cc10: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 okaside memory.
cc20: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 The first.** ar
cc30: 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 gument may be NU
cc40: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 LL in which case
cc50: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c SQLite will all
cc60: 6f 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 ocate the lookas
cc70: 69 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 ide.** buffer it
cc80: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 self using [sqli
cc90: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 te3_malloc()].
cca0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
ccb0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 ent is the.** si
ccc0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 ze of each looka
ccd0: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 side buffer slot
cce0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 and the third a
ccf0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e rgument is the n
cd00: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
cd10: 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 s. The size of
cd20: 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 the buffer in th
cd30: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
cd40: 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 must be greater
cd50: 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 than.** or equa
cd60: 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 l to the product
cd70: 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
cd80: 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e nd third argumen
cd90: 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ts.</dd>.**.** <
cda0: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
cdb0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
cdc0: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 LOOKASIDE 100
cdd0: 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 1 /* void* int
cde0: 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 int */.../*.** C
cdf0: 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 API3REF: Enable
ce00: 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e Or Disable Exten
ce10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
ce20: 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 {H12200} <S1070
ce30: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
ce40: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
ce50: 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 sult_codes() rou
ce60: 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
ce70: 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 disables the.**
ce80: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
ce90: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 codes] feature
cea0: 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 of SQLite. The e
ceb0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a xtended result.*
cec0: 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 * codes are disa
ced0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
cee0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 for historical c
cef0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e ompatibility con
cf00: 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a siderations..**.
cf10: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
cf20: 0a 2a 2a 20 5b 48 31 32 32 30 31 5d 20 5b 48 31 .** [H12201] [H1
cf30: 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2202].*/.int sql
cf40: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
cf50: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
cf60: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
cf70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
cf80: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
cf90: 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 wid {H12220} <S1
cfa0: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 0700>.**.** Each
cfb0: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c entry in an SQL
cfc0: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 ite table has a
cfd0: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 unique 64-bit si
cfe0: 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 gned.** integer
cff0: 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b key called the [
d000: 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d ROWID | "rowid"]
d010: 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 . The rowid is a
d020: 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a lways available.
d030: 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 ** as an undecla
d040: 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 red column named
d050: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 ROWID, OID, or
d060: 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 _ROWID_ as long
d070: 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 as those.** name
d080: 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 s are not also u
d090: 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c sed by explicitl
d0a0: 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d y declared colum
d0b0: 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 ns. If.** the ta
d0c0: 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e ble has a column
d0d0: 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 of type [INTEGE
d0e0: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 R PRIMARY KEY] t
d0f0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a hen that column.
d100: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c ** is another al
d110: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 ias for the rowi
d120: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f d..**.** This ro
d130: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
d140: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
d150: 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 most recent.**
d160: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
d170: 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 RT] into the dat
d180: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b abase from the [
d190: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
d1a0: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ion].** in the f
d1b0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 irst argument.
d1c0: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
d1d0: 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 [INSERT]s.** ha
d1e0: 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 ve ever occurred
d1f0: 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 on that databas
d200: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 e connection, ze
d210: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a ro is returned..
d220: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53 **.** If an [INS
d230: 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 ERT] occurs with
d240: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 in a trigger, th
d250: 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f en the [rowid] o
d260: 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a f the inserted.*
d270: 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 * row is returne
d280: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e d by this routin
d290: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 e as long as the
d2a0: 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e trigger is runn
d2b0: 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 ing..** But once
d2c0: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 the trigger ter
d2d0: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c minates, the val
d2e0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
d2f0: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 his routine.** r
d300: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 everts to the la
d310: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 st value inserte
d320: 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 d before the tri
d330: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a gger fired..**.*
d340: 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 * An [INSERT] th
d350: 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 at fails due to
d360: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
d370: 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a lation is not a.
d380: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 ** successful [I
d390: 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 NSERT] and does
d3a0: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
d3b0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
d3c0: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
d3d0: 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f . Thus INSERT O
d3e0: 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f R FAIL, INSERT O
d3f0: 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 R IGNORE, INSERT
d400: 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a OR ROLLBACK,.**
d410: 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 and INSERT OR A
d420: 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 BORT make no cha
d430: 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 nges to the retu
d440: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
d450: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e .** routine when
d460: 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e their insertion
d470: 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e fails. When IN
d480: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a SERT OR REPLACE.
d490: 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 ** encounters a
d4a0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
d4b0: 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f tion, it does no
d4c0: 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 t fail. The.**
d4d0: 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 INSERT continues
d4e0: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 to completion a
d4f0: 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f fter deleting ro
d500: 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a ws that caused.*
d510: 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 * the constraint
d520: 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 problem so INSE
d530: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 RT OR REPLACE wi
d540: 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 ll always change
d550: 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 .** the return v
d560: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 alue of this int
d570: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f erface..**.** Fo
d580: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f r the purposes o
d590: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 f this routine,
d5a0: 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 an [INSERT] is c
d5b0: 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 onsidered to.**
d5c0: 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 be successful ev
d5d0: 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 en if it is subs
d5e0: 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 equently rolled
d5f0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 back..**.** Requ
d600: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
d610: 32 32 32 31 5d 20 5b 48 31 32 32 32 33 5d 0a 2a 2221] [H12223].*
d620: 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
d630: 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 te thread perfor
d640: 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 ms a new [INSERT
d650: 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a ] on the same.**
d660: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
d670: 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b tion while the [
d680: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
d690: 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 ert_rowid()].**
d6a0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
d6b0: 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 ing and thus cha
d6c0: 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e nges the last in
d6d0: 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a sert [rowid],.**
d6e0: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
d6f0: 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
d700: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
d710: 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 _rowid()] is.**
d720: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
d730: 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 d might not equa
d740: 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 l either the old
d750: 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c or the new.** l
d760: 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 ast insert [rowi
d770: 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 d]..*/.sqlite3_i
d780: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 nt64 sqlite3_las
d790: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
d7a0: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
d7b0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 CAPI3REF: Count
d7c0: 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 The Number Of R
d7d0: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 ows Modified {H1
d7e0: 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2240} <S10600>.*
d7f0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
d800: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
d810: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 umber of databas
d820: 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 e rows that were
d830: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 changed.** or i
d840: 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
d850: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 ed by the most r
d860: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
d870: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a d SQL statement.
d880: 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 ** on the [datab
d890: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
d8a0: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
d8b0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
d8c0: 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 ..** Only change
d8d0: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 s that are direc
d8e0: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 tly specified by
d8f0: 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b the [INSERT], [
d900: 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b UPDATE],.** or [
d910: 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e DELETE] statemen
d920: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 t are counted.
d930: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 Auxiliary change
d940: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 s caused by.** t
d950: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 riggers are not
d960: 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 counted. Use the
d970: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
d980: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 changes()] funct
d990: 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 ion.** to find t
d9a0: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 he total number
d9b0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 of changes inclu
d9c0: 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 ding changes cau
d9d0: 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e sed by triggers.
d9e0: 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 .**.** A "row ch
d9f0: 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 ange" is a chang
da00: 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f e to a single ro
da10: 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 w of a single ta
da20: 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 ble.** caused by
da30: 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 an INSERT, DELE
da40: 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 TE, or UPDATE st
da50: 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 atement. Rows t
da60: 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 hat.** are chang
da70: 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 ed as side effec
da80: 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f ts of REPLACE co
da90: 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
daa0: 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b ion,.** rollback
dab0: 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 , ABORT processi
dac0: 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 ng, DROP TABLE,
dad0: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a or by any other.
dae0: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f ** mechanisms do
daf0: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 not count as di
db00: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 rect row changes
db10: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 ..**.** A "trigg
db20: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 er context" is a
db30: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 scope of execut
db40: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 ion that begins
db50: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 and.** ends with
db60: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 the script of a
db70: 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 trigger. Most
db80: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
db90: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 re.** evaluated
dba0: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 outside of any t
dbb0: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 rigger. This is
dbc0: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 the "top level"
dbd0: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
dbe0: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 ext. If a trigg
dbf0: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 er fires from th
dc00: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a e top level, a.*
dc10: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f * new trigger co
dc20: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 ntext is entered
dc30: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f for the duratio
dc40: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a n of that one.**
dc50: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 trigger. Subtr
dc60: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 iggers create su
dc70: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 bcontexts for th
dc80: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a eir duration..**
dc90: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c .** Calling [sql
dca0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 ite3_exec()] or
dcb0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
dcc0: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 recursively doe
dcd0: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 s.** not create
dce0: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f a new trigger co
dcf0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ntext..**.** Thi
dd00: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
dd10: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
dd20: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e direct row chan
dd30: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f ges in the.** mo
dd40: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 st recent INSERT
dd50: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
dd60: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 ETE statement wi
dd70: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a thin the same.**
dd80: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
dd90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 ..**.** Thus, wh
dda0: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 en called from t
ddb0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 he top level, th
ddc0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
ddd0: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 rns the.** numbe
dde0: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 r of changes in
ddf0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
de00: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
de10: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
de20: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 t also occurred
de30: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c at the top level
de40: 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f . Within the bo
de50: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c dy of a trigger,
de60: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f .** the sqlite3_
de70: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 changes() interf
de80: 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ace can be calle
de90: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
dea0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 mber of.** chang
deb0: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 es in the most r
dec0: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
ded0: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 d INSERT, UPDATE
dee0: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 , or DELETE.** s
def0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
df00: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 the body of the
df10: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a same trigger..**
df20: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 However, the nu
df30: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f mber returned do
df40: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 es not include c
df50: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 hanges.** caused
df60: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 by subtriggers
df70: 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 since those have
df80: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 their own conte
df90: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 xt..**.** SQLite
dfa0: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
dfb0: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 command "DELETE
dfc0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 FROM table" with
dfd0: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 out a WHERE clau
dfe0: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e se.** by droppin
dff0: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 g and recreating
e000: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 44 6f 69 the table. Doi
e010: 6e 67 20 73 6f 20 69 73 20 6d 75 63 68 20 66 61 ng so is much fa
e020: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a ster than going.
e030: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 ** through and d
e040: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 eleting individu
e050: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d al elements from
e060: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 42 65 63 the table. Bec
e070: 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 ause of this.**
e080: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 optimization, th
e090: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 e deletions in "
e0a0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
e0b0: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 e" are not row c
e0c0: 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 hanges and.** wi
e0d0: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 ll not be counte
e0e0: 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
e0f0: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 _changes() or [s
e100: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
e110: 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 nges()].** funct
e120: 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 ions, regardless
e130: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
e140: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 f elements that
e150: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a were originally.
e160: 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e ** in the table.
e170: 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 To get an accu
e180: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 rate count of th
e190: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
e1a0: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a deleted, use.**
e1b0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 "DELETE FROM ta
e1c0: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 ble WHERE 1" ins
e1d0: 74 65 61 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70 tead. Or recomp
e1e0: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ile using the.**
e1f0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 [SQLITE_OMIT_TR
e200: 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 UNCATE_OPTIMIZAT
e210: 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ION] compile-tim
e220: 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 e option to disa
e230: 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d ble the.** optim
e240: 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 ization on all q
e250: 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 ueries..**.** Re
e260: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
e270: 48 31 32 32 34 31 5d 20 5b 48 31 32 32 34 33 5d H12241] [H12243]
e280: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
e290: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
e2a0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
e2b0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
e2c0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
e2d0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e le [sqlite3_chan
e2e0: 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
e2f0: 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
e300: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
e310: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
e320: 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
e330: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
e340: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
e350: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
e360: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 REF: Total Numbe
e370: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
e380: 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 ed {H12260} <S10
e390: 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
e3a0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
e3b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
e3c0: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ow changes cause
e3d0: 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 d by INSERT,.**
e3e0: 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 UPDATE or DELETE
e3f0: 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 statements sinc
e400: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 e the [database
e410: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 connection] was
e420: 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 opened..** The c
e430: 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c ount includes al
e440: 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 l changes from a
e450: 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ll trigger conte
e460: 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a xts. However,.*
e470: 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 * the count does
e480: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 not include cha
e490: 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 nges used to imp
e4a0: 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 lement REPLACE c
e4b0: 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 onstraints,.** d
e4c0: 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 o rollbacks or A
e4d0: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
e4e0: 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 or DROP table p
e4f0: 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 rocessing..** Th
e500: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f e changes are co
e510: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 unted as soon as
e520: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
e530: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 hat makes them i
e540: 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 s.** completed (
e550: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 when the stateme
e560: 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 nt handle is pas
e570: 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f sed to [sqlite3_
e580: 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
e590: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
e5a0: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ()])..**.** SQLi
e5b0: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
e5c0: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 e command "DELET
e5d0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 E FROM table" wi
e5e0: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c thout a WHERE cl
e5f0: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 ause.** by dropp
e600: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 ing and recreati
e610: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 ng the table. (
e620: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 This is much fas
e630: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a ter than going.*
e640: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 * through and de
e650: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 leting individua
e660: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 l elements from
e670: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 the table.) Bec
e680: 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 ause of this.**
e690: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 optimization, th
e6a0: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 e deletions in "
e6b0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
e6c0: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 e" are not row c
e6d0: 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 hanges and.** wi
e6e0: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 ll not be counte
e6f0: 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
e700: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 _changes() or [s
e710: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
e720: 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 nges()].** funct
e730: 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 ions, regardless
e740: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
e750: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 f elements that
e760: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a were originally.
e770: 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e ** in the table.
e780: 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 To get an accu
e790: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 rate count of th
e7a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
e7b0: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a deleted, use.**
e7c0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 "DELETE FROM ta
e7d0: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 ble WHERE 1" ins
e7e0: 74 65 61 64 2e 20 20 20 4f 72 20 72 65 63 6f 6d tead. Or recom
e7f0: 70 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a pile using the.*
e800: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 * [SQLITE_OMIT_T
e810: 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 RUNCATE_OPTIMIZA
e820: 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 TION] compile-ti
e830: 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 me option to dis
e840: 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 able the.** opti
e850: 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 mization on all
e860: 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 queries..**.** S
e870: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
e880: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
e890: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
e8a0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
e8b0: 2a 20 5b 48 31 32 32 36 31 5d 20 5b 48 31 32 32 * [H12261] [H122
e8c0: 36 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 63].**.** If a s
e8d0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
e8e0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
e8f0: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
e900: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
e910: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 while [sqlite3_t
e920: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
e930: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
e940: 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 the value.** ret
e950: 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 urned is unpredi
e960: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
e970: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e eaningful..*/.in
e980: 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f t sqlite3_total_
e990: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a changes(sqlite3*
e9a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
e9b0: 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 EF: Interrupt A
e9c0: 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 Long-Running Que
e9d0: 72 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 ry {H12270} <S30
e9e0: 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 500>.**.** This
e9f0: 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
ea00: 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
ea10: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
ea20: 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
ea30: 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
ea40: 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
ea50: 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
ea60: 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
ea70: 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
ea80: 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
ea90: 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
eaa0: 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
eab0: 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
eac0: 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
ead0: 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
eae0: 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
eaf0: 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
eb00: 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 *.** It is safe
eb10: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
eb20: 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 tine from a thre
eb30: 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f ad different fro
eb40: 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 m the.** thread
eb50: 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c that is currentl
eb60: 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 y running the da
eb70: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
eb80: 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 . But it.** is
eb90: 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c not safe to call
eba0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
ebb0: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
ebc0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a onnection] that.
ebd0: 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 ** is closed or
ebe0: 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f might close befo
ebf0: 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 re sqlite3_inter
ec00: 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a rupt() returns..
ec10: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 **.** If an SQL
ec20: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 operation is ver
ec30: 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 y nearly finishe
ec40: 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 d at the time wh
ec50: 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e en.** sqlite3_in
ec60: 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c terrupt() is cal
ec70: 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 led, then it mig
ec80: 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f ht not have an o
ec90: 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f pportunity.** to
eca0: 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 be interrupted
ecb0: 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e and might contin
ecc0: 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e ue to completion
ecd0: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f ..**.** An SQL o
ece0: 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 peration that is
ecf0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c interrupted wil
ed00: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
ed10: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 _INTERRUPT]..**
ed20: 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 If the interrupt
ed30: 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e ed SQL operation
ed40: 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 is an INSERT, U
ed50: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
ed60: 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 .** that is insi
ed70: 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 de an explicit t
ed80: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
ed90: 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e the entire tran
eda0: 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 saction.** will
edb0: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 be rolled back a
edc0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a utomatically..**
edd0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
ede0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
edf0: 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 ) has no effect
ee00: 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
ee10: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
ee20: 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 arted after sqli
ee30: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
ee40: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 returns..**.** R
ee50: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
ee60: 5b 48 31 32 32 37 31 5d 20 5b 48 31 32 32 37 32 [H12271] [H12272
ee70: 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 ].**.** If the d
ee80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ee90: 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 on closes while
eea0: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
eeb0: 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e pt()].** is runn
eec0: 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 ing then bad thi
eed0: 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ngs will likely
eee0: 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 happen..*/.void
eef0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
ef00: 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
ef10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
ef20: 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
ef30: 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 L Statement Is C
ef40: 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d omplete {H10510}
ef50: 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70200>.**.**
ef60: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
ef70: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f re useful for co
ef80: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 mmand-line input
ef90: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 to determine if
efa0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c the.** currentl
efb0: 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 y entered text s
efc0: 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d eems to form com
efd0: 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 plete a SQL stat
efe0: 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 ement or.** if a
eff0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 dditional input
f000: 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 is needed before
f010: 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 sending the tex
f020: 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 t into.** SQLite
f030: 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 for parsing. T
f040: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
f050: 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 turn true if the
f060: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a input string.**
f070: 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 appears to be a
f080: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
f090: 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 atement. A stat
f0a0: 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 ement is judged
f0b0: 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 to be.** complet
f0c0: 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 e if it ends wit
f0d0: 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f h a semicolon to
f0e0: 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ken and is not a
f0f0: 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a fragment of a.*
f100: 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 * CREATE TRIGGER
f110: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d statement. Sem
f120: 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
f130: 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
f140: 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
f150: 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
f160: 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
f170: 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
f180: 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
f190: 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
f1a0: 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
f1b0: 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
f1c0: 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
f1d0: 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
f1e0: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
f1f0: 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
f200: 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 tor..**.** These
f210: 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 routines do not
f220: 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 parse the SQL s
f230: 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a tatements thus.*
f240: 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 * will not detec
f250: 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 t syntactically
f260: 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a incorrect SQL..*
f270: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
f280: 73 3a 20 5b 48 31 30 35 31 31 5d 20 5b 48 31 30 s: [H10511] [H10
f290: 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 512].**.** The i
f2a0: 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
f2b0: 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 _complete()] mus
f2c0: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
f2d0: 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 inated.** UTF-8
f2e0: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 string..**.** Th
f2f0: 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 e input to [sqli
f300: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
f310: 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f ] must be a zero
f320: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
f330: 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 TF-16 string in
f340: 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
f350: 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 r..*/.int sqlite
f360: 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 3_complete(const
f370: 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 char *sql);.int
f380: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
f390: 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a e16(const void *
f3a0: 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 sql);../*.** CAP
f3b0: 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 I3REF: Register
f3c0: 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 A Callback To Ha
f3d0: 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 ndle SQLITE_BUSY
f3e0: 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d Errors {H12310}
f3f0: 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S40400>.**.**
f400: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
f410: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
f420: 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 ction that might
f430: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
f440: 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d ever.** an attem
f450: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 pt is made to op
f460: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 en a database ta
f470: 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 ble that another
f480: 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 thread.** or pr
f490: 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 ocess has locked
f4a0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 ..**.** If the b
f4b0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
f4c0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 NULL, then [SQLI
f4d0: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c TE_BUSY] or [SQL
f4e0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
f4f0: 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 D].** is returne
f500: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 d immediately up
f510: 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 on encountering
f520: 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 the lock. If the
f530: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a busy callback.*
f540: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 * is not NULL, t
f550: 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
f560: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
f570: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 with two argume
f580: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nts..**.** The f
f590: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
f5a0: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 the handler is
f5b0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f a copy of the vo
f5c0: 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 id* pointer whic
f5d0: 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 h.** is the thir
f5e0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
f5f0: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
f600: 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e er(). The secon
f610: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
f620: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c the handler cal
f630: 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d lback is the num
f640: 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 ber of times tha
f650: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c t the busy handl
f660: 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 er has.** been i
f670: 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 nvoked for this
f680: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 locking event.
f690: 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 If the.** busy c
f6a0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
f6b0: 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 0, then no addit
f6c0: 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 ional attempts a
f6d0: 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 re made to.** ac
f6e0: 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 cess the databas
f6f0: 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 e and [SQLITE_BU
f700: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
f710: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 OERR_BLOCKED] is
f720: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 returned..** If
f730: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
f740: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
f750: 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 then another att
f760: 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 empt.** is made
f770: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
f780: 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 base for reading
f790: 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 and the cycle r
f7a0: 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 epeats..**.** Th
f7b0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 e presence of a
f7c0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 busy handler doe
f7d0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 s not guarantee
f7e0: 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 that it will be
f7f0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 invoked.** when
f800: 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f there is lock co
f810: 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c ntention. If SQL
f820: 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 ite determines t
f830: 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 hat invoking the
f840: 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 busy.** handler
f850: 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e could result in
f860: 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 a deadlock, it
f870: 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e will go ahead an
f880: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
f890: 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 _BUSY].** or [SQ
f8a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
f8b0: 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 ED] instead of i
f8c0: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
f8d0: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e handler..** Con
f8e0: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f sider a scenario
f8f0: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 where one proce
f900: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
f910: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a read lock that.*
f920: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 * it is trying t
f930: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 o promote to a r
f940: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 eserved lock and
f950: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f .** a second pro
f960: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
f970: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
f980: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e that it is tryin
f990: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 g.** to promote
f9a0: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 to an exclusive
f9b0: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 lock. The first
f9c0: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 process cannot
f9d0: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 proceed.** becau
f9e0: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
f9f0: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
fa00: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 nd the second pr
fa10: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 ocess cannot.**
fa20: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 proceed because
fa30: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
fa40: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 the first. If
fa50: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a both processes.*
fa60: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 * invoke the bus
fa70: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 y handlers, neit
fa80: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e her will make an
fa90: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 y progress. The
faa0: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 refore,.** SQLit
fab0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
fac0: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 E_BUSY] for the
fad0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 first process, h
fae0: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a oping that this.
faf0: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 ** will induce t
fb00: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
fb10: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 to release its
fb20: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c read lock and al
fb30: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e low.** the secon
fb40: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f d process to pro
fb50: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ceed..**.** The
fb60: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c default busy cal
fb70: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a lback is NULL..*
fb80: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
fb90: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 _BUSY] error is
fba0: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 converted to [SQ
fbb0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
fbc0: 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ED].** when SQLi
fbd0: 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 te is in the mid
fbe0: 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 dle of a large t
fbf0: 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 ransaction where
fc00: 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e all the.** chan
fc10: 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 ges will not fit
fc20: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d into the in-mem
fc30: 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 ory cache. SQLi
fc40: 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 te will.** alrea
fc50: 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 dy hold a RESERV
fc60: 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 ED lock on the d
fc70: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 atabase file, bu
fc80: 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f t it needs.** to
fc90: 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f promote this lo
fca0: 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 ck to EXCLUSIVE
fcb0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 so that it can s
fcc0: 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 pill cache.** pa
fcd0: 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 ges into the dat
fce0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f abase file witho
fcf0: 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 ut harm to concu
fd00: 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 rrent.** readers
fd10: 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 . If it is unab
fd20: 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 le to promote th
fd30: 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 e lock, then the
fd40: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 in-memory.** ca
fd50: 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 che will be left
fd60: 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 in an inconsist
fd70: 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f ent state and so
fd80: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f the error.** co
fd90: 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 de is promoted f
fda0: 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 rom the relative
fdb0: 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 ly benign [SQLIT
fdc0: 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 E_BUSY] to.** th
fdd0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 e more severe [S
fde0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
fdf0: 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f KED]. This erro
fe00: 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e r code promotion
fe10: 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 .** forces an au
fe20: 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b tomatic rollback
fe30: 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e of the changes.
fe40: 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 See the.** <a
fe50: 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 href="/cvstrac/w
fe60: 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e iki?p=Corruption
fe70: 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
fe80: 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 or">.** Corrupti
fe90: 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 onFollowingBusyE
fea0: 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 rror</a> wiki pa
feb0: 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 ge for a discuss
fec0: 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 ion of why.** th
fed0: 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e is is important.
fee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e .**.** There can
fef0: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
ff00: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 e busy handler d
ff10: 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a efined for each.
ff20: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
ff30: 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 nection]. Setti
ff40: 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 ng a new busy ha
ff50: 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 ndler clears any
ff60: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
ff70: 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 et handler. Not
ff80: 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b e that calling [
ff90: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
ffa0: 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 eout()].** will
ffb0: 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 also set or clea
ffc0: 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c r the busy handl
ffd0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 er..**.** The bu
ffe0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 sy callback shou
fff0: 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 ld not take any
10000 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f actions which mo
10010 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 dify the.** data
10020 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
10030 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
10040 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 busy handler.
10050 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 Any such actions
10060 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e .** result in un
10070 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
10080 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65 ..** .** Require
10090 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 ments:.** [H1231
100a0 31 5d 20 5b 48 31 32 33 31 32 5d 20 5b 48 31 32 1] [H12312] [H12
100b0 33 31 34 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48 314] [H12316] [H
100c0 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 12318].**.** A b
100d0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 usy handler must
100e0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 not close the d
100f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10100 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 on.** or [prepar
10110 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
10120 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
10130 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a usy handler..*/.
10140 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
10150 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
10160 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
10170 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
10180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
10190 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
101a0 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 t {H12340} <S404
101b0 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 10>.**.** This r
101c0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 outine sets a [s
101d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
101e0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c ler | busy handl
101f0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a er] that sleeps.
10200 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 ** for a specifi
10210 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d ed amount of tim
10220 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 e when a table i
10230 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 s locked. The h
10240 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
10250 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
10260 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
10270 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
10280 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
10290 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
102a0 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 ated. {H12343} A
102b0 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 fter "ms" millis
102c0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
102d0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
102e0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
102f0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
10300 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
10310 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
10320 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
10330 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
10340 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 .**.** Calling t
10350 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
10360 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
10370 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
10380 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
10390 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
103a0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ndlers..**.** Th
103b0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
103c0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
103d0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
103e0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
103f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
10400 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
10410 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
10420 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
10430 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
10440 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
10450 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
10460 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
10470 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
10480 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
10490 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
104a0 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ared..**.** Requ
104b0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
104c0 32 33 34 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b 2341] [H12343] [
104d0 48 31 32 33 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73 H12344].*/.int s
104e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
104f0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e out(sqlite3*, in
10500 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t ms);../*.** CA
10510 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 PI3REF: Convenie
10520 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 nce Routines For
10530 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 Running Queries
10540 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30 {H12370} <S1000
10550 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 0>.**.** Definit
10560 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 ion: A <b>result
10570 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 table</b> is me
10580 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 mory data struct
10590 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 ure created by t
105a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 he.** [sqlite3_g
105b0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 et_table()] inte
105c0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 rface. A result
105d0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 table records t
105e0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 he.** complete q
105f0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f uery results fro
10600 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 m one or more qu
10610 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eries..**.** The
10620 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 table conceptua
10630 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 lly has a number
10640 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c of rows and col
10650 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 umns. But.** th
10660 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 ese numbers are
10670 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 not part of the
10680 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 result table its
10690 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e elf. These.** n
106a0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 umbers are obtai
106b0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 ned separately.
106c0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 Let N be the nu
106d0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 mber of rows.**
106e0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d and M be the num
106f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a ber of columns..
10700 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
10710 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 able is an array
10720 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
10730 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
10740 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a UTF-8 strings..*
10750 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 * There are (N+1
10760 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 )*M elements in
10770 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 the array. The
10780 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 first M pointers
10790 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 point.** to zer
107a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
107b0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 ings that conta
107c0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 in the names of
107d0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 the columns..**
107e0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e The remaining en
107f0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 tries all point
10800 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 to query results
10810 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 . NULL values r
10820 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c esult.** in NULL
10830 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 pointers. All
10840 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 other values are
10850 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 in their UTF-8
10860 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
10870 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 ** string repres
10880 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 entation as retu
10890 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
108a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e _column_text()].
108b0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
108c0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 table might cons
108d0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f ist of one or mo
108e0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 re memory alloca
108f0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 tions..** It is
10900 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 not safe to pass
10910 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 a result table
10920 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c directly to [sql
10930 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
10940 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
10950 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f should be deallo
10960 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cated using [sql
10970 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
10980 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 )]..**.** As an
10990 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 example of the r
109a0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d esult table form
109b0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 at, suppose a qu
109c0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ery result.** is
109d0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
109e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
109f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e pre>.** N
10a00 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 ame | Age
10a10 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d .** -----
10a20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
10a30 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 --.** Ali
10a40 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a ce | 43.**
10a50 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 Bob
10a60 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 | 28.**
10a70 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c Cindy |
10a80 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 21.** </pre></b
10a90 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
10aa0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 There are two c
10ab0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 olumn (M==2) and
10ac0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d three rows (N==
10ad0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 3). Thus the.**
10ae0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 result table ha
10af0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 s 8 entries. Su
10b00 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 ppose the result
10b10 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 table is stored
10b20 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 .** in an array
10b30 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 names azResult.
10b40 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 Then azResult h
10b50 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e olds this conten
10b60 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 t:.**.** <blockq
10b70 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
10b80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
10b90 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 1;0] = "Name";.*
10ba0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
10bb0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 t[1] = "Age"
10bc0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
10bd0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 sult[2] = "A
10be0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 lice";.**
10bf0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d azResult[3]
10c00 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 = "43";.**
10c10 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
10c20 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 4] = "Bob";.**
10c30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
10c40 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 91;5] = "28";.**
10c50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
10c60 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 [6] = "Cindy
10c70 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
10c80 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 esult[7] = "
10c90 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 21";.** </pre></
10ca0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
10cb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
10cc0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 t_table() functi
10cd0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 on evaluates one
10ce0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 or more.** semi
10cf0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 colon-separated
10d00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
10d10 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 n the zero-termi
10d20 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 nated UTF-8.** s
10d30 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 tring of its 2nd
10d40 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 parameter. It
10d50 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 returns a result
10d60 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a table to the.**
10d70 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 pointer given i
10d80 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 n its 3rd parame
10d90 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 ter..**.** After
10da0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e the calling fun
10db0 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 ction has finish
10dc0 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 ed using the res
10dd0 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a ult, it should.*
10de0 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 * pass the point
10df0 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 er to the result
10e00 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 table to sqlite
10e10 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 3_free_table() i
10e20 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 n order to.** re
10e30 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
10e40 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 that was malloc
10e50 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 ed. Because of
10e60 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b the way the.** [
10e70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
10e80 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e ] happens within
10e90 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
10ea0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e le(), the callin
10eb0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 g.** function mu
10ec0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 st not try to ca
10ed0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ll [sqlite3_free
10ee0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f ()] directly. O
10ef0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nly.** [sqlite3_
10f00 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 free_table()] is
10f10 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 able to release
10f20 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 the memory prop
10f30 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e erly and safely.
10f40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
10f50 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 e3_get_table() i
10f60 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c nterface is impl
10f70 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 emented as a wra
10f80 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
10f90 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e sqlite3_exec()].
10fa0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 The sqlite3_ge
10fb0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e t_table() routin
10fc0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 e does not have
10fd0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 access.** to any
10fe0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 internal data s
10ff0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c tructures of SQL
11000 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e ite. It uses on
11010 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a ly the public.**
11020 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e interface defin
11030 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 ed here. As a c
11040 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f onsequence, erro
11050 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e rs that occur in
11060 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 the.** wrapper
11070 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 layer outside of
11080 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 the internal [s
11090 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 qlite3_exec()] c
110a0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 all are not.** r
110b0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 eflected in subs
110c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
110d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
110e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
110f0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a errmsg()]..**.**
11100 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
11110 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48 31 32 33 * [H12371] [H123
11120 37 33 5d 20 5b 48 31 32 33 37 34 5d 20 5b 48 31 73] [H12374] [H1
11130 32 33 37 36 5d 20 5b 48 31 32 33 37 39 5d 20 5b 2376] [H12379] [
11140 48 31 32 33 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73 H12382].*/.int s
11150 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
11160 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
11170 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
11180 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
11190 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
111a0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 Sql, /* SQL
111b0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 to be evaluated
111c0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a */. char ***paz
111d0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 Result, /* Re
111e0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 sults of the que
111f0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 ry */. int *pnR
11200 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a ow, /*
11210 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
11220 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 t rows written h
11230 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ere */. int *pn
11240 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f Column, /
11250 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
11260 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 lt columns writt
11270 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 en here */. cha
11280 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 r **pzErrmsg
11290 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
112a0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
112b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
112c0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 free_table(char
112d0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a **result);../*.*
112e0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d * CAPI3REF: Form
112f0 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 atted String Pri
11300 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 nting Functions
11310 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30 {H17400} <S70000
11320 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 ><S20000>.**.**
11330 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
11340 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 re workalikes of
11350 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 the "printf()"
11360 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 family of functi
11370 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 ons.** from the
11380 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
11390 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ry..**.** The sq
113a0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 lite3_mprintf()
113b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 and sqlite3_vmpr
113c0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 intf() routines
113d0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 write their.** r
113e0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f esults into memo
113f0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
11400 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
11410 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 ()]..** The stri
11420 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
11430 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e these two routin
11440 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 es should be.**
11450 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c released by [sql
11460 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 ite3_free()]. B
11470 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 oth routines ret
11480 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f urn a.** NULL po
11490 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 inter if [sqlite
114a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 3_malloc()] is u
114b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
114c0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f e enough.** memo
114d0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 ry to hold the r
114e0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e esulting string.
114f0 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 .**.** In sqlite
11500 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 3_snprintf() rou
11510 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 tine is similar
11520 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 to "snprintf()"
11530 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e from.** the stan
11540 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 dard C library.
11550 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 The result is w
11560 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a ritten into the.
11570 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 ** buffer suppli
11580 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
11590 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 parameter whose
115a0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 size is given b
115b0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 y.** the first p
115c0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 arameter. Note t
115d0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 hat the order of
115e0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 the.** first tw
115f0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 o parameters is
11600 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e reversed from sn
11610 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 printf(). This
11620 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 is an.** histori
11630 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 cal accident tha
11640 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 t cannot be fixe
11650 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
11660 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 ng.** backwards
11670 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 compatibility.
11680 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 Note also that s
11690 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
116a0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 ).** returns a p
116b0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 ointer to its bu
116c0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 ffer instead of
116d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
116e0 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 characters actu
116f0 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 ally written int
11700 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 o the buffer. W
11710 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 e admit that.**
11720 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
11730 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e aracters written
11740 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 would be a more
11750 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a useful return.*
11760 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 * value but we c
11770 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 annot change the
11780 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
11790 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
117a0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 ntf().** now wit
117b0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f hout breaking co
117c0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a mpatibility..**.
117d0 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 ** As long as th
117e0 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 e buffer size is
117f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 greater than ze
11800 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 ro, sqlite3_snpr
11810 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e intf().** guaran
11820 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 tees that the bu
11830 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a ffer is always z
11840 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero-terminated.
11850 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 The first.** pa
11860 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 rameter "n" is t
11870 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 he total size of
11880 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 the buffer, inc
11890 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 luding space for
118a0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 .** the zero ter
118b0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 minator. So the
118c0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 longest string
118d0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 that can be comp
118e0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 letely.** writte
118f0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 n will be n-1 ch
11900 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
11910 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
11920 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d ll implement som
11930 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 e additional for
11940 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f matting.** optio
11950 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 ns that are usef
11960 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 ul for construct
11970 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ing SQL statemen
11980 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 ts..** All of th
11990 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 e usual printf()
119a0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
119b0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 ons apply. In a
119c0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a ddition, there.*
119d0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 * is are "%q", "
119e0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 %Q", and "%z" op
119f0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tions..**.** The
11a00 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %q option works
11a10 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 like %s in that
11a20 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 it substitutes
11a30 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 a null-terminate
11a40 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d d.** string from
11a50 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 the argument li
11a60 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f st. But %q also
11a70 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 doubles every '
11a80 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a \'' character..*
11a90 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 * %q is designed
11aa0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 for use inside
11ab0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
11ac0 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 . By doubling e
11ad0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 ach '\''.** char
11ae0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 acter it escapes
11af0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 that character
11b00 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f and allows it to
11b10 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 be inserted int
11b20 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e o.** the string.
11b30 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 .**.** For examp
11b40 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 le, assume the s
11b50 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a tring variable z
11b60 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 Text contains te
11b70 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a xt as follows:.*
11b80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
11b90 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
11ba0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 *zText = "It's a
11bb0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a happy day!";.**
11bc0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
11bd0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 ote>.**.** One c
11be0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 an use this text
11bf0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 in an SQL state
11c00 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a ment as follows:
11c10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
11c20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
11c30 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 r *zSQL = sqlite
11c40 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 3_mprintf("INSER
11c50 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c T INTO table VAL
11c60 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 UES('%q')", zTex
11c70 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
11c80 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
11c90 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
11ca0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
11cb0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
11cc0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 kquote>.**.** Be
11cd0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 cause the %q for
11ce0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 mat string is us
11cf0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 ed, the '\'' cha
11d00 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a racter in zText.
11d10 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e ** is escaped an
11d20 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 d the SQL genera
11d30 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 ted is as follow
11d40 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
11d50 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
11d60 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
11d70 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 1 VALUES('It''s
11d80 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a a happy day!').*
11d90 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
11da0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
11db0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 is correct. Ha
11dc0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 d we used %s ins
11dd0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 tead of %q, the
11de0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a generated SQL.**
11df0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b would have look
11e00 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ed like this:.**
11e10 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
11e20 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
11e30 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
11e40 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 UES('It's a happ
11e50 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 y day!');.** </p
11e60 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
11e70 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f .**.** This seco
11e80 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e nd example is an
11e90 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f SQL syntax erro
11ea0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c r. As a general
11eb0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 rule you should
11ec0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 .** always use %
11ed0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 q instead of %s
11ee0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 when inserting t
11ef0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e ext into a strin
11f00 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a g literal..**.**
11f10 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 The %Q option w
11f20 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 orks like %q exc
11f30 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 ept it also adds
11f40 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 single quotes a
11f50 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 round.** the out
11f60 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 side of the tota
11f70 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 l string. Addit
11f80 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 ionally, if the
11f90 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
11fa0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .** argument lis
11fb0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
11fc0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 ter, %Q substitu
11fd0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 tes the text "NU
11fe0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 LL" (without.**
11ff0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69 single quotes) i
12000 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 n place of the %
12010 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 Q option. So, f
12020 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 or example, one
12030 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a could say:.**.**
12040 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
12050 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
12060 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
12070 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
12080 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 table VALUES(%Q
12090 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
120a0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
120b0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
120c0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
120d0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
120e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
120f0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 **.** The code a
12100 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 bove will render
12110 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 a correct SQL s
12120 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
12130 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 zSQL.** variable
12140 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 even if the zTe
12150 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 xt variable is a
12160 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
12170 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f *.** The "%z" fo
12180 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 rmatting option
12190 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 works exactly li
121a0 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65 ke "%s" with the
121b0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 .** addition tha
121c0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 t after the stri
121d0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 ng has been read
121e0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f and copied into
121f0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 .** the result,
12200 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
12210 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 is called on th
12220 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 e input string.
12230 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 {END}.**.** Requ
12240 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
12250 37 34 30 33 5d 20 5b 48 31 37 34 30 36 5d 20 5b 7403] [H17406] [
12260 48 31 37 34 30 37 5d 0a 2a 2f 0a 63 68 61 72 20 H17407].*/.char
12270 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 *sqlite3_mprintf
12280 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
12290 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
122a0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
122b0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
122c0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 .char *sqlite3_s
122d0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
122e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
122f0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
12300 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
12310 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
12320 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 m {H17300} <S200
12330 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 00>.**.** The SQ
12340 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 Lite core uses
12350 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 these three rout
12360 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 ines for all of
12370 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 its own.** inter
12380 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
12390 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f ation needs. "Co
123a0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 re" in the previ
123b0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 ous sentence.**
123c0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
123d0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 operating-syste
123e0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 m specific VFS i
123f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
12400 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 The.** Windows V
12410 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d FS uses native m
12420 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
12430 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 () for some oper
12440 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ations..**.** Th
12450 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
12460 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
12470 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
12480 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 a block.** of me
12490 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 mory at least N
124a0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c bytes in length,
124b0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
124c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 parameter..** If
124d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
124e0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f ) is unable to o
124f0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 btain sufficient
12500 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c free.** memory,
12510 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 it returns a NU
12520 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 LL pointer. If
12530 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
12540 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
12550 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
12560 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
12570 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
12580 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
12590 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
125a0 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 * Calling sqlite
125b0 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 3_free() with a
125c0 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 pointer previous
125d0 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ly returned.** b
125e0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
125f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
12600 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 alloc() releases
12610 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a that memory so.
12620 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 ** that it might
12630 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 be reused. The
12640 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
12650 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 routine is.** a
12660 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c no-op if is call
12670 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
12680 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 ointer. Passing
12690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
126a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 ** to sqlite3_fr
126b0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 ee() is harmless
126c0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 . After being f
126d0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 reed, memory.**
126e0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 should neither b
126f0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 e read nor writt
12700 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e en. Even readin
12710 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 g previously fre
12720 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 ed.** memory mig
12730 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 ht result in a s
12740 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
12750 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 t or other sever
12760 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f e error..** Memo
12770 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 ry corruption, a
12780 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
12790 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 ult, or other se
127a0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 vere error.** mi
127b0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 ght result if sq
127c0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
127d0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f called with a no
127e0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 n-NULL pointer t
127f0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f hat.** was not o
12800 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
12810 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
12820 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
12830 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ()..**.** The sq
12840 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
12850 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
12860 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
12870 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
12880 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
12890 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
128a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
128b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
128c0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 eter. The memor
128d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
128e0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 be resized is th
128f0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
12900 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 eter. If the fi
12910 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
12920 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
12930 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 ().** is a NULL
12940 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
12950 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
12960 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
12970 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
12980 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 loc(N) where N i
12990 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
129a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
129b0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
129c0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
129d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
129e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 e3_realloc() is
129f0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 zero or.** negat
12a00 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 ive then the beh
12a10 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 avior is exactly
12a20 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c the same as cal
12a30 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
12a40 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 free(P) where P
12a50 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
12a60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
12a70 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
12a80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
12a90 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
12aa0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
12ab0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
12ac0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
12ad0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c s in size or NUL
12ae0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 L if sufficient
12af0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 memory is unavai
12b00 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 lable..** If M i
12b10 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
12b20 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
12b30 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d on, then min(N,M
12b40 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 ) bytes.** of th
12b50 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
12b60 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e on are copied in
12b70 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
12b80 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 of buffer retur
12b90 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
12ba0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 3_realloc() and
12bb0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
12bc0 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a tion is freed..*
12bd0 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 * If sqlite3_rea
12be0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e lloc() returns N
12bf0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 ULL, then the pr
12c00 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ior allocation.*
12c10 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a * is not freed..
12c20 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 **.** The memory
12c30 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
12c40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e ite3_malloc() an
12c50 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f d sqlite3_reallo
12c60 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 c().** is always
12c70 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c aligned to at l
12c80 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 east an 8 byte b
12c90 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a oundary. {END}.*
12ca0 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 *.** The default
12cb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
12cc0 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c of the memory al
12cd0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
12ce0 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d em uses.** the m
12cf0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 alloc(), realloc
12d00 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 () and free() pr
12d10 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 ovided by the st
12d20 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
12d30 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f ..** {H17382} Ho
12d40 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 wever, if SQLite
12d50 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
12d60 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
12d70 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e MEMORY_SIZE=<i>N
12d80 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 NN</i> C preproc
12d90 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 essor macro (whe
12da0 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a re <i>NNN</i>.**
12db0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c is an integer),
12dc0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 then SQLite cre
12dd0 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72 ate a static arr
12de0 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a ay of at least.*
12df0 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 * <i>NNN</i> byt
12e00 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 es in size and u
12e10 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66 ses that array f
12e20 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 or all of its dy
12e30 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 namic.** memory
12e40 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
12e50 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f . {END} Additio
12e60 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
12e70 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 ator options.**
12e80 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
12e90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
12ea0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 .**.** In SQLite
12eb0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 version 3.5.0 a
12ec0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 nd 3.5.1, it was
12ed0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 possible to def
12ee0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 ine.** the SQLIT
12ef0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c E_OMIT_MEMORY_AL
12f00 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 LOCATION which w
12f10 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 ould cause the b
12f20 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 uilt-in.** imple
12f30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
12f40 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 se routines to b
12f50 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 e omitted. That
12f60 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
12f70 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 s no longer prov
12f80 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c ided. Only buil
12f90 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
12fa0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 cators can be us
12fb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 ed..**.** The Wi
12fc0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 ndows OS interfa
12fd0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a ce layer calls.*
12fe0 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c * the system mal
12ff0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
13000 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 directly when c
13010 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c onverting.** fil
13020 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 enames between t
13030 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e he UTF-8 encodin
13040 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 g used by SQLite
13050 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 .** and whatever
13060 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 filename encodi
13070 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 ng is used by th
13080 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e e particular Win
13090 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 dows.** installa
130a0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c tion. Memory al
130b0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 location errors
130c0 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 are detected, bu
130d0 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 t.** they are re
130e0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b ported back as [
130f0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
13100 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 or.** [SQLITE_I
13110 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 OERR] rather tha
13120 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
13130 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
13140 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 30 33 ents:.** [H17303
13150 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48 31 37 33 ] [H17304] [H173
13160 30 35 5d 20 5b 48 31 37 33 30 36 5d 20 5b 48 31 05] [H17306] [H1
13170 37 33 31 30 5d 20 5b 48 31 37 33 31 32 5d 20 5b 7310] [H17312] [
13180 48 31 37 33 31 35 5d 20 5b 48 31 37 33 31 38 5d H17315] [H17318]
13190 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20 5b 48 31 .** [H17321] [H1
131a0 37 33 32 32 5d 20 5b 48 31 37 33 32 33 5d 0a 2a 7322] [H17323].*
131b0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 *.** The pointer
131c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 arguments to [s
131d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 qlite3_free()] a
131e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
131f0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 loc()].** must b
13200 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 e either NULL or
13210 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f else pointers o
13220 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 btained from a p
13230 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 rior.** invocati
13240 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d on of [sqlite3_m
13250 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c alloc()] or [sql
13260 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 ite3_realloc()]
13270 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 that have.** not
13280 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 yet been releas
13290 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 ed..**.** The ap
132a0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
132b0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 ot read or write
132c0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 any part of.**
132d0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 a block of memor
132e0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 y after it has b
132f0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 een released usi
13300 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ng.** [sqlite3_f
13310 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 ree()] or [sqlit
13320 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a e3_realloc()]..*
13330 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
13340 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 malloc(int);.voi
13350 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d *sqlite3_reall
13360 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a oc(void*, int);.
13370 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
13380 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a e(void*);../*.**
13390 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
133a0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 y Allocator Stat
133b0 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 istics {H17370}
133c0 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 <S30210>.**.** S
133d0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 QLite provides t
133e0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 hese two interfa
133f0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e ces for reportin
13400 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a g on the status.
13410 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
13420 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 e3_malloc()], [s
13430 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 qlite3_free()],
13440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
13450 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 lloc()].** routi
13460 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 nes, which form
13470 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d the built-in mem
13480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
13490 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 ubsystem..**.**
134a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
134b0 20 5b 48 31 37 33 37 31 5d 20 5b 48 31 37 33 37 [H17371] [H1737
134c0 33 5d 20 5b 48 31 37 33 37 34 5d 20 5b 48 31 37 3] [H17374] [H17
134d0 33 37 35 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 375].*/.sqlite3_
134e0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
134f0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b mory_used(void);
13500 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
13510 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
13520 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 ghwater(int rese
13530 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 tFlag);../*.** C
13540 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d API3REF: Pseudo-
13550 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 Random Number Ge
13560 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d nerator {H17390}
13570 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20000>.**.**
13580 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 SQLite contains
13590 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 a high-quality p
135a0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d seudo-random num
135b0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 ber generator (P
135c0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 RNG) used to.**
135d0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 select random [R
135e0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 OWID | ROWIDs] w
135f0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 hen inserting ne
13600 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 w records into a
13610 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 table that.** a
13620 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 lready uses the
13630 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 largest possible
13640 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 [ROWID]. The P
13650 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
13660 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
13670 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
13680 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
13690 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
136a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
136b0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 lows.** applicat
136c0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 ions to access t
136d0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 he same PRNG for
136e0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e other purposes.
136f0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
13700 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 this routine st
13710 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 ores N bytes of
13720 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
13730 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 buffer P..**.**
13740 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 The first time t
13750 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 his routine is i
13760 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 nvoked (either i
13770 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a nternally or by.
13780 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
13790 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 on) the PRNG is
137a0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e seeded using ran
137b0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
137c0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 .** from the xRa
137d0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 ndomness method
137e0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
137f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
13800 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 ect..** On all s
13810 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 ubsequent invoca
13820 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 tions, the pseud
13830 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 o-randomness is
13840 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 generated.** int
13850 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 ernally and with
13860 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 out recourse to
13870 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
13880 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a ] xRandomness.**
13890 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 method..**.** R
138a0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
138b0 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 76 6f 69 64 [H17392].*/.void
138c0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e sqlite3_randomn
138d0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 ess(int N, void
138e0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *P);../*.** CAPI
138f0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 3REF: Compile-Ti
13900 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e me Authorization
13910 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 Callbacks {H125
13920 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 00} <S70100>.**.
13930 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
13940 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 registers a auth
13950 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
13960 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
13970 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
13980 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 onnection], supp
13990 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 lied in the firs
139a0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 t argument..** T
139b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
139c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
139d0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 d as SQL stateme
139e0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f nts are being co
139f0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 mpiled.** by [sq
13a00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
13a10 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
13a20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
13a30 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c e_v2()],.** [sql
13a40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
13a50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
13a60 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 repare16_v2()].
13a70 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 At various.** p
13a80 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 oints during the
13a90 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f compilation pro
13aa0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 cess, as logic i
13ab0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a s being created.
13ac0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ** to perform va
13ad0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 rious actions, t
13ae0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
13af0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
13b00 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 d to.** see if t
13b10 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 hose actions are
13b20 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 allowed. The a
13b30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
13b40 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ck should.** ret
13b50 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
13b60 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 to allow the act
13b70 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e ion, [SQLITE_IGN
13b80 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 ORE] to disallow
13b90 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
13ba0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f action but allo
13bb0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d w the SQL statem
13bc0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 ent to continue
13bd0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 to be.** compile
13be0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 d, or [SQLITE_DE
13bf0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 NY] to cause the
13c00 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 entire SQL stat
13c10 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 ement to be.** r
13c20 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 ejected with an
13c30 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 error. If the a
13c40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
13c50 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ck returns.** an
13c60 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
13c70 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 an [SQLITE_IGNOR
13c80 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c E], [SQLITE_OK],
13c90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
13ca0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 ].** then the [s
13cb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
13cc0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
13cd0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
13ce0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 ggered.** the au
13cf0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
13d00 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
13d10 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 message..**.**
13d20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
13d30 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
13d40 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e E_OK], that mean
13d50 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a s the operation.
13d60 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 ** requested is
13d70 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 ok. When the ca
13d80 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
13d90 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 SQLITE_DENY], th
13da0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
13db0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
13dc0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
13dd0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
13de0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
13df0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
13e00 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
13e10 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a explaining that.
13e20 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e ** access is den
13e30 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 ied. If the aut
13e40 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 horizer code is
13e50 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a [SQLITE_READ].**
13e60 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
13e70 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
13e80 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
13e90 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
13ea0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 statement] state
13eb0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 ment is construc
13ec0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 ted to substitut
13ed0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 e.** a NULL valu
13ee0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 e in place of th
13ef0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 e table column t
13f00 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a hat would have.*
13f10 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b * been read if [
13f20 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 SQLITE_OK] had b
13f30 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 een returned. T
13f40 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 he [SQLITE_IGNOR
13f50 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e E].** return can
13f60 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 be used to deny
13f70 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 an untrusted us
13f80 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 er access to ind
13f90 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d ividual.** colum
13fa0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a ns of a table..*
13fb0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
13fc0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
13fd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
13fe0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
13ff0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
14000 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
14010 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
14020 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 rizer() interfac
14030 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 e. The second pa
14040 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
14050 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
14060 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 integer [SQLITE
14070 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 _COPY | action c
14080 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
14090 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 ies.** the parti
140a0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 cular action to
140b0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 be authorized. T
140c0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 he third through
140d0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 sixth parameter
140e0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c s.** to the call
140f0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 back are zero-te
14100 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
14110 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 that contain ad
14120 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 ditional.** deta
14130 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 ils about the ac
14140 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
14150 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 rized..**.** An
14160 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
14170 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
14180 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
14190 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
141a0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
141b0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
141c0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
141d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
141e0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
141f0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
14200 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
14210 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
14220 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
14230 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
14240 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
14250 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
14260 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
14270 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
14280 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
14290 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
142a0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
142b0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
142c0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
142d0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
142e0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
142f0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
14300 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
14310 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
14320 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
14330 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
14340 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
14350 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
14360 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
14370 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
14380 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
14390 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
143a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
143b0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
143c0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
143d0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
143e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
143f0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
14400 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
14410 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
14420 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
14430 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
14440 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
14450 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
14460 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
14470 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
14480 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
14490 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
144a0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
144b0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
144c0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
144d0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
144e0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c rizer..**.** Onl
144f0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
14500 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
14510 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
14520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
14530 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
14540 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
14550 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
14560 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
14570 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
14580 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 . Disable the a
14590 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 uthorizer by ins
145a0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 talling a NULL c
145b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 allback..** The
145c0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 authorizer is di
145d0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
145e0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 t..**.** The aut
145f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
14600 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
14610 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
14620 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
14630 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14640 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
14650 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
14660 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 llback..** Note
14670 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
14680 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
14690 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
146a0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
146b0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
146c0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
146d0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
146e0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
146f0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
14700 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
14710 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
14720 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
14730 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
14740 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
14750 68 74 20 62 65 20 72 65 70 72 65 70 61 72 65 64 ht be reprepared
14760 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 during [sqlite3
14770 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 _step()] due to
14780 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 a .** schema cha
14790 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 nge. Hence, the
147a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
147b0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 uld ensure that
147c0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 the.** correct a
147d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
147e0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c ck remains in pl
147f0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b ace during the [
14800 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
14810 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
14820 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
14830 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
14840 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a ked only during.
14850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
14860 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
14870 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 riants. Authori
14880 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a zation is not.**
14890 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e performed durin
148a0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c g statement eval
148b0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 uation in [sqlit
148c0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a e3_step()]..**.*
148d0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
148e0 2a 2a 20 5b 48 31 32 35 30 31 5d 20 5b 48 31 32 ** [H12501] [H12
148f0 35 30 32 5d 20 5b 48 31 32 35 30 33 5d 20 5b 48 502] [H12503] [H
14900 31 32 35 30 34 5d 20 5b 48 31 32 35 30 35 5d 20 12504] [H12505]
14910 5b 48 31 32 35 30 36 5d 20 5b 48 31 32 35 30 37 [H12506] [H12507
14920 5d 20 5b 48 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 ] [H12510].** [H
14930 31 32 35 31 31 5d 20 5b 48 31 32 35 31 32 5d 20 12511] [H12512]
14940 5b 48 31 32 35 32 30 5d 20 5b 48 31 32 35 32 31 [H12520] [H12521
14950 5d 20 5b 48 31 32 35 32 32 5d 0a 2a 2f 0a 69 6e ] [H12522].*/.in
14960 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 t sqlite3_set_au
14970 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 thorizer(. sqli
14980 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 te3*,. int (*xA
14990 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 uth)(void*,int,c
149a0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
149b0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
149c0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c r*,const char*),
149d0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 . void *pUserDa
149e0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ta.);../*.** CAP
149f0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
14a00 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b r Return Codes {
14a10 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e H12590} <H12500>
14a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
14a30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
14a40 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
14a50 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
14a60 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 n] must.** retur
14a70 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 n either [SQLITE
14a80 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 _OK] or one of t
14a90 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e hese two constan
14aa0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 ts in order.** t
14ab0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 o signal SQLite
14ac0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
14ad0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 he action is per
14ae0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 mitted. See the
14af0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
14b00 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
14b10 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e thorizer documen
14b20 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 tation] for addi
14b30 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
14b40 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e ation..*/.#defin
14b50 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 e SQLITE_DENY
14b60 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 1 /* Abort the
14b70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
14b80 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ith an error */.
14b90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
14ba0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e GNORE 2 /* Don
14bb0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 't allow access,
14bc0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 but don't gener
14bd0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ate an error */.
14be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
14bf0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 Authorizer Acti
14c00 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 on Codes {H12550
14c10 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a } <H12500>.**.**
14c20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
14c30 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
14c40 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
14c50 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
14c60 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
14c70 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
14c80 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
14c90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
14ca0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
14cb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
14cc0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
14cd0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
14ce0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
14cf0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
14d00 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
14d10 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
14d20 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
14d30 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
14d40 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
14d50 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
14d60 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
14d70 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
14d80 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
14d90 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
14da0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
14db0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
14dc0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
14dd0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
14de0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
14df0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
14e00 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
14e10 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
14e20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
14e30 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
14e40 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
14e50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
14e60 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 eter. The 5th p
14e70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a arameter to the.
14e80 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ** authorizer ca
14e90 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 llback is the na
14ea0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
14eb0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d se ("main", "tem
14ec0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 p",.** etc.) if
14ed0 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 applicable. The
14ee0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
14ef0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
14f00 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
14f10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
14f20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
14f30 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
14f40 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
14f50 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
14f60 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
14f70 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
14f80 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
14f90 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
14fa0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
14fb0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
14fc0 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 35 31 5d 20 ts:.** [H12551]
14fd0 5b 48 31 32 35 35 32 5d 20 5b 48 31 32 35 35 33 [H12552] [H12553
14fe0 5d 20 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a ] [H12554].*/./*
14ff0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15000 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a ********** 3rd *
15020 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 *********** 4th
15030 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 ***********/.#de
15040 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
15050 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 TE_INDEX
15060 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 1 /* Index N
15070 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
15080 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
15090 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
150a0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 E_TABLE
150b0 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 2 /* Table Na
150c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
150d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
150e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
150f0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
15100 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 3 /* Index Nam
15110 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
15120 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
15130 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
15140 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 TEMP_TABLE 4
15150 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
15160 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
15170 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
15180 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
15190 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 EMP_TRIGGER 5
151a0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
151b0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
151c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
151d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
151e0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 MP_VIEW 6
151f0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
15200 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
15210 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15220 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 QLITE_CREATE_TRI
15230 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 GGER 7
15240 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
15250 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
15260 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
15270 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 LITE_CREATE_VIEW
15280 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 8 /
15290 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
152a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
152b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
152c0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ITE_DELETE
152d0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 9 /*
152e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
152f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
15300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15310 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 TE_DROP_INDEX
15320 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 10 /*
15330 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
15340 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
15350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15360 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 E_DROP_TABLE
15370 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 11 /* T
15380 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
15390 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
153a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
153b0 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 _DROP_TEMP_INDEX
153c0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 12 /* In
153d0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
153e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
153f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15400 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 DROP_TEMP_TABLE
15410 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 13 /* Tab
15420 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
15430 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
15440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15450 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ROP_TEMP_TRIGGER
15460 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 14 /* Trig
15470 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
15480 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
15490 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
154a0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 OP_TEMP_VIEW
154b0 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 15 /* View
154c0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
154d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
154e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
154f0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 P_TRIGGER
15500 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 16 /* Trigge
15510 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
15520 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
15530 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
15540 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
15550 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 17 /* View Na
15560 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
15570 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
15580 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 ine SQLITE_INSER
15590 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
155a0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 18 /* Table Na
155b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
155c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
155d0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 ne SQLITE_PRAGMA
155e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
155f0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 9 /* Pragma Na
15600 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f me 1st arg o
15610 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e r NULL */.#defin
15620 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 e SQLITE_READ
15630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
15640 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
15650 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
15660 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
15670 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 SQLITE_SELECT
15680 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 21
15690 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
156a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
156b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
156c0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 SQLITE_TRANSACTI
156d0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 ON 22
156e0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
156f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
15700 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15710 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 QLITE_UPDATE
15720 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 23
15730 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
15740 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
15750 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
15760 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 LITE_ATTACH
15770 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 24 /
15780 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 * Filename
15790 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
157a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
157b0 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 ITE_DETACH
157c0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 25 /*
157d0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
157e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
157f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15800 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 TE_ALTER_TABLE
15810 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 26 /*
15820 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
15830 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
15840 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15850 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 E_REINDEX
15860 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 27 /* I
15870 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e ndex Name N
15880 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
15890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
158a0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 _ANALYZE
158b0 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 28 /* Ta
158c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
158d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
158e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
158f0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 CREATE_VTABLE
15900 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 29 /* Tab
15910 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
15920 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
15930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15940 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ROP_VTABLE
15950 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 30 /* Tabl
15960 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
15970 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
15980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
15990 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 NCTION
159a0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 31 /* NULL
159b0 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 Funct
159c0 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 ion Name */.#d
159d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 efine SQLITE_SAV
159e0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 EPOINT
159f0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 32 /* Operat
15a00 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f ion Savepo
15a10 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 int Name */.#de
15a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 fine SQLITE_COPY
15a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
15a40 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 0 /* No long
15a50 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a er used */../*.*
15a60 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 * CAPI3REF: Trac
15a70 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e ing And Profilin
15a80 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 g Functions {H12
15a90 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 280} <S60400>.**
15aa0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
15ab0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
15ac0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c es register call
15ad0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 back functions t
15ae0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 hat can be used
15af0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 for.** tracing a
15b00 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 nd profiling the
15b10 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 execution of SQ
15b20 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
15b30 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b .** The callback
15b40 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
15b50 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
15b60 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b trace() is invok
15b70 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 ed at.** various
15b80 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 times when an S
15b90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 QL statement is
15ba0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 being run by [sq
15bb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
15bc0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 * The callback r
15bd0 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 eturns a UTF-8 r
15be0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
15bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
15c00 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 xt.** as the sta
15c10 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 tement first beg
15c20 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 ins executing.
15c30 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 Additional callb
15c40 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 acks occur.** as
15c50 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 each triggered
15c60 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e subprogram is en
15c70 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c tered. The call
15c80 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 backs for trigge
15c90 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 rs.** contain a
15ca0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e UTF-8 SQL commen
15cb0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 t that identifie
15cc0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a s the trigger..*
15cd0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
15ce0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
15cf0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
15d00 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
15d10 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
15d20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
15d30 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 inishes. The pr
15d40 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 ofile callback c
15d50 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f ontains.** the o
15d60 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
15d70 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 t text and an es
15d80 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 timate of wall-c
15d90 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 lock time.** of
15da0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 how long that st
15db0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
15dc0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 run..**.** Requi
15dd0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
15de0 32 38 31 5d 20 5b 48 31 32 32 38 32 5d 20 5b 48 281] [H12282] [H
15df0 31 32 32 38 33 5d 20 5b 48 31 32 32 38 34 5d 20 12283] [H12284]
15e00 5b 48 31 32 32 38 35 5d 20 5b 48 31 32 32 38 37 [H12285] [H12287
15e10 5d 20 5b 48 31 32 32 38 38 5d 20 5b 48 31 32 32 ] [H12288] [H122
15e20 38 39 5d 0a 2a 2a 20 5b 48 31 32 32 39 30 5d 0a 89].** [H12290].
15e30 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
15e40 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c MENTAL void *sql
15e50 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 ite3_trace(sqlit
15e60 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 e3*, void(*xTrac
15e70 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
15e80 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 har*), void*);.S
15e90 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
15ea0 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 AL void *sqlite3
15eb0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 _profile(sqlite3
15ec0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f *,. void(*xPro
15ed0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 file)(void*,cons
15ee0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f t char*,sqlite3_
15ef0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b uint64), void*);
15f00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
15f10 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 : Query Progress
15f20 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 Callbacks {H129
15f30 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 10} <S60400>.**.
15f40 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
15f50 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c configures a cal
15f60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d lback function -
15f70 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 the.** progress
15f80 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 callback - that
15f90 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 is invoked peri
15fa0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
15fb0 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 long.** running
15fc0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
15fd0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 3_exec()], [sqli
15fe0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a te3_step()] and.
15ff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
16000 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 table()]. An ex
16010 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 ample use for th
16020 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 is.** interface
16030 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 is to keep a GUI
16040 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 updated during
16050 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a a large query..*
16060 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 *.** If the prog
16070 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 ress callback re
16080 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
16090 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 the operation is
160a0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e .** interrupted.
160b0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 This feature c
160c0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d an be used to im
160d0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 plement a.** "Ca
160e0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 ncel" button on
160f0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 a GUI progress d
16100 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a ialog box..**.**
16110 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 The progress ha
16120 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 ndler must not d
16130 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
16140 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
16150 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
16160 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
16170 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
16180 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
16190 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
161a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
161b0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
161c0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
161d0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
161e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
161f0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
16200 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
16210 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
16220 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
16230 2a 2a 20 5b 48 31 32 39 31 31 5d 20 5b 48 31 32 ** [H12911] [H12
16240 39 31 32 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48 912] [H12913] [H
16250 31 32 39 31 34 5d 20 5b 48 31 32 39 31 35 5d 20 12914] [H12915]
16260 5b 48 31 32 39 31 36 5d 20 5b 48 31 32 39 31 37 [H12916] [H12917
16270 5d 20 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f ] [H12918].**.*/
16280 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 .void sqlite3_pr
16290 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 ogress_handler(s
162a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e qlite3*, int, in
162b0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
162c0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
162d0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 3REF: Opening A
162e0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e New Database Con
162f0 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d nection {H12700}
16300 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S40200>.**.**
16310 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
16320 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
16330 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 tabase file whos
16340 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 e name is given
16350 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 by the.** filena
16360 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 me argument. The
16370 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
16380 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 nt is interprete
16390 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a d as UTF-8 for.*
163a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
163b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
163c0 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 n_v2() and as UT
163d0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
163e0 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 ve byte.** order
163f0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 for sqlite3_ope
16400 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 n16(). A [databa
16410 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
16420 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 andle is usually
16430 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 .** returned in
16440 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 *ppDb, even if a
16450 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
16460 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 The only except
16470 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 ion is that.** i
16480 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 f SQLite is unab
16490 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
164a0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
164b0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
164c0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 ct,.** a NULL wi
164d0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e ll be written in
164e0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 to *ppDb instead
164f0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f of a pointer to
16500 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a the [sqlite3].*
16510 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 * object. If the
16520 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
16530 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
16540 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
16550 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
16560 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
16570 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
16580 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
16590 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
165a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
165b0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 msg()] or [sqlit
165c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 e3_errmsg16()] r
165d0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
165e0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
165f0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
16600 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
16610 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a of the error..*
16620 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 *.** The default
16630 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 encoding for th
16640 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
16650 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 be UTF-8 if.** s
16660 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
16670 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
16680 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 () is called and
16690 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 .** UTF-16 in th
166a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
166b0 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f der if sqlite3_o
166c0 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e pen16() is used.
166d0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f .**.** Whether o
166e0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f r not an error o
166f0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 ccurs when it is
16700 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 opened, resourc
16710 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 es.** associated
16720 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
16730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
16740 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
16750 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 released by.**
16760 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
16770 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
16780 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
16790 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a nger required..*
167a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
167b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 _open_v2() inter
167c0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 face works like
167d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
167e0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
167f0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 accepts two add
16800 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
16810 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
16820 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 l control.** ove
16830 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 r the new databa
16840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
16850 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
16860 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 ter can take one
16870 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f of.** the follo
16880 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 wing three value
16890 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f s, optionally co
168a0 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 mbined with the
168b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
168c0 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 _NOMUTEX] or [SQ
168d0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
168e0 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a TEX] flags:.**.*
168f0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 * <dl>.** <dt>[S
16900 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
16910 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NLY]</dt>.** <dd
16920 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
16930 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d opened in read-
16940 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 only mode. If t
16950 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
16960 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 not.** already
16970 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
16980 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
16990 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c >.**.** <dt>[SQL
169a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
169b0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
169c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
169d0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
169e0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
169f0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
16a00 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
16a10 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
16a20 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
16a30 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
16a40 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
16a50 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
16a60 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
16a70 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
16a80 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
16a90 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a returned.</dd>.
16aa0 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 **.** <dt>[SQLIT
16ab0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
16ac0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
16ad0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a _CREATE]</dt>.**
16ae0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
16af0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
16b00 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
16b10 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 ing, and is crea
16b20 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 tes it if.** it
16b30 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
16b40 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
16b50 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
16b60 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
16b70 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
16b80 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
16b90 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
16ba0 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a >.** </dl>.**.**
16bb0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
16bc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
16bd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
16be0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
16bf0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
16c00 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 wn above or one
16c10 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 of the combinati
16c20 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
16c30 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 combined.** with
16c40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
16c50 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 N_NOMUTEX] or [S
16c60 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
16c70 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 UTEX] flags,.**
16c80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
16c90 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
16ca0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 **.** If the [SQ
16cb0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
16cc0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
16cd0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
16ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
16cf0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
16d00 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
16d10 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
16d20 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
16d30 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
16d40 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
16d50 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
16d60 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
16d70 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 If the.** [SQLI
16d80 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
16d90 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 X] flag is set t
16da0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
16db0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
16dc0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 s.** in the seri
16dd0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
16de0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 g mode] unless s
16df0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 ingle-thread was
16e00 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
16e10 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
16e20 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
16e30 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 -time..**.** If
16e40 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
16e50 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e ":memory:", then
16e60 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
16e70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 orary in-memory
16e80 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 database.** is c
16e90 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 reated for the c
16ea0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 onnection. This
16eb0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
16ec0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 ase will vanish
16ed0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 when.** the data
16ee0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
16ef0 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 is closed. Futu
16f00 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
16f10 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d QLite might.** m
16f20 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 ake use of addit
16f30 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 ional special fi
16f40 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 lenames that beg
16f50 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 in with the ":"
16f60 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 character..** It
16f70 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
16f80 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 that when a data
16f90 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 base filename ac
16fa0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 tually does begi
16fb0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 n with.** a ":"
16fc0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 character you sh
16fd0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 ould prefix the
16fe0 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 filename with a
16ff0 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 pathname such as
17000 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 .** "./" to avoi
17010 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a d ambiguity..**.
17020 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 ** If the filena
17030 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 me is an empty s
17040 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 tring, then a pr
17050 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
17060 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 .** on-disk data
17070 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
17080 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 ated. This priv
17090 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c ate database wil
170a0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 l be.** automati
170b0 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 cally deleted as
170c0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 soon as the dat
170d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
170e0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a is closed..**.*
170f0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 * The fourth par
17100 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
17110 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 3_open_v2() is t
17120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
17130 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
17140 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
17150 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e nes the operatin
17160 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
17170 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e ce that.** the n
17180 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
17190 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 ection should us
171a0 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 e. If the fourt
171b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
171c0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
171d0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c then the defaul
171e0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
171f0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a object is used..
17200 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
17210 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c Windows users:<
17220 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e /b> The encodin
17230 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 g used for the f
17240 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
17250 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f .** of sqlite3_o
17260 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
17270 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 3_open_v2() must
17280 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 be UTF-8, not w
17290 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 hatever.** codep
172a0 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 age is currently
172b0 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e defined. Filen
172c0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ames containing
172d0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a international.**
172e0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 characters must
172f0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f be converted to
17300 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 UTF-8 prior to
17310 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 passing them int
17320 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
17330 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
17340 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 pen_v2()..**.**
17350 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
17360 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32 37 30 [H12701] [H1270
17370 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48 31 32 2] [H12703] [H12
17380 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b 48 704] [H12706] [H
17390 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39 5d 20 12707] [H12709]
173a0 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31 32 [H12711].** [H12
173b0 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b 48 712] [H12713] [H
173c0 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37 5d 20 12714] [H12717]
173d0 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37 32 31 [H12719] [H12721
173e0 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 69 6e ] [H12723].*/.in
173f0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
17400 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
17410 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
17420 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
17430 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
17440 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
17450 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
17460 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
17470 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
17480 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
17490 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
174a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
174b0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
174c0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
174d0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
174e0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
174f0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
17500 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
17510 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
17520 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
17530 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
17540 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
17550 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
17560 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
17570 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
17580 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
17590 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
175a0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
175b0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
175c0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
175d0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
175e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
175f0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
17600 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 And Messages {H1
17610 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2800} <S60200>.*
17620 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
17630 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 _errcode() inter
17640 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
17650 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 numeric [result
17660 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 code] or.** [ex
17670 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
17680 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 de] for the most
17690 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 recent failed s
176a0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c qlite3_* API cal
176b0 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 l.** associated
176c0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
176d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 connection]. If
176e0 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c a prior API cal
176f0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 l failed.** but
17700 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
17710 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 API call succeed
17720 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ed, the return v
17730 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c alue from.** sql
17740 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
17750 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 68 s undefined. Th
17760 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
17770 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
17780 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
17790 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
177a0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
177b0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
177c0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
177d0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
177e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
177f0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
17800 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
17810 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 lite3_errmsg() a
17820 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 nd sqlite3_errms
17830 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 g16() return Eng
17840 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a lish-language.**
17850 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 text that descr
17860 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 ibes the error,
17870 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
17880 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 or UTF-16 respec
17890 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 tively..** Memor
178a0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 y to hold the er
178b0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
178c0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e ng is managed in
178d0 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 ternally..** The
178e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 application doe
178f0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f s not need to wo
17900 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e rry about freein
17910 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a g the result..**
17920 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 However, the er
17930 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 ror string might
17940 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 be overwritten
17950 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 or deallocated b
17960 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 y.** subsequent
17970 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 calls to other S
17980 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 QLite interface
17990 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a functions..**.**
179a0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c When the serial
179b0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
179c0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c mode] is in use,
179d0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 it might be the
179e0 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 .** case that a
179f0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 second error occ
17a00 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 urs on a separat
17a10 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 e thread in betw
17a20 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 een.** the time
17a30 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 of the first err
17a40 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 or and the call
17a50 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
17a60 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 ces..** When tha
17a70 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 t happens, the s
17a80 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c econd error will
17a90 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e be reported sin
17aa0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 ce these.** inte
17ab0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 rfaces always re
17ac0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 port the most re
17ad0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f cent result. To
17ae0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 avoid.** this,
17af0 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 each thread can
17b00 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 obtain exclusive
17b10 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 use of the [dat
17b20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
17b30 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 ] D.** by invoki
17b40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
17b50 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 x_enter]([sqlite
17b60 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 3_db_mutex](D))
17b70 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 before beginning
17b80 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 .** to use D and
17b90 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
17ba0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 e3_mutex_leave](
17bb0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
17bc0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 x](D)) after.**
17bd0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 all calls to the
17be0 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 interfaces list
17bf0 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 ed here are comp
17c00 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 leted..**.** If
17c10 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 an interface fai
17c20 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d ls with SQLITE_M
17c30 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e ISUSE, that mean
17c40 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a s the interface.
17c50 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 ** was invoked i
17c60 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 ncorrectly by th
17c70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
17c80 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 In that case, th
17c90 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 e.** error code
17ca0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 and message may
17cb0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 or may not be se
17cc0 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 t..**.** Require
17cd0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38 30 ments:.** [H1280
17ce0 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 48 31 32 1] [H12802] [H12
17cf0 38 30 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b 48 803] [H12807] [H
17d00 31 32 38 30 38 5d 20 5b 48 31 32 38 30 39 5d 0a 12808] [H12809].
17d10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
17d20 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
17d30 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 db);.int sqlite3
17d40 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
17d50 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
17d60 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
17d70 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 te3_errmsg(sqlit
17d80 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 e3*);.const void
17d90 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
17da0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 16(sqlite3*);../
17db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
17dc0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a QL Statement Obj
17dd0 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 ect {H13000} <H1
17de0 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 3010>.** KEYWORD
17df0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
17e00 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
17e10 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
17e20 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
17e30 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
17e40 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
17e50 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
17e60 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
17e70 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e is variously kn
17e80 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 own as a "prepar
17e90 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 ed statement" or
17ea0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a.** "compiled
17eb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
17ec0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
17ed0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a tatement"..**.**
17ee0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 The life of a s
17ef0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
17f00 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c goes something l
17f10 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
17f20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 <ol>.** <li> Cre
17f30 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 ate the object u
17f40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
17f50 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 epare_v2()] or a
17f60 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 related.**
17f70 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c function..** <l
17f80 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
17f90 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 o [host paramete
17fa0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 rs] using the sq
17fb0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
17fc0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 * interface
17fd0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 s..** <li> Run t
17fe0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e he SQL by callin
17ff0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
18000 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 )] one or more t
18010 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 imes..** <li> Re
18020 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e set the statemen
18030 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
18040 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
18050 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
18060 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
18070 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
18080 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
18090 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
180a0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
180b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
180c0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 </ol>.**.** Ref
180d0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 er to documentat
180e0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
180f0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 l methods above
18100 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
18110 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
18120 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
18130 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 sqlite3_stmt sq
18140 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a lite3_stmt;../*.
18150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
18160 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 -time Limits {H1
18170 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2760} <S20600>.*
18180 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
18190 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
181a0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
181b0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
181c0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
181d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
181e0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
181f0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
18200 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
18210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18220 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
18230 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
18240 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
18250 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
18260 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
18270 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
18280 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
18290 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
182a0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
182b0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
182c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
182d0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
182e0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
182f0 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 onstruct. The f
18300 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
18310 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a the old limit..*
18320 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 *.** If the new
18330 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
18340 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
18350 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
18360 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c ed..** For the l
18370 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 imit category of
18380 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 SQLITE_LIMIT_XY
18390 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a Z there is a .**
183a0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 [limits | hard
183b0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 upper bound].**
183c0 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 set by a compile
183d0 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 -time C preproce
183e0 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 ssor macro named
183f0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 .** [limits | S
18400 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a QLITE_MAX_XYZ]..
18410 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f ** (The "_LIMIT_
18420 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 " in the name is
18430 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 changed to "_MA
18440 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 X_".).** Attempt
18450 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 s to increase a
18460 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 limit above its
18470 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
18480 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 are.** silently
18490 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 truncated to th
184a0 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d e hard upper lim
184b0 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 it..**.** Run ti
184c0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
184d0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
184e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
184f0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
18500 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
18510 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
18520 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
18530 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
18540 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
18550 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
18560 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
18570 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
18580 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
18590 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 b browser that h
185a0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 as its own datab
185b0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 ases for storing
185c0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 history and.**
185d0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 separate databas
185e0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 es controlled by
185f0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c JavaScript appl
18600 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 ications downloa
18610 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 ded.** off the I
18620 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e nternet. The in
18630 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 ternal databases
18640 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 can be given th
18650 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 e.** large, defa
18660 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 ult limits. Dat
18670 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 abases managed b
18680 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 y external sourc
18690 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 es can.** be giv
186a0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 en much smaller
186b0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 limits designed
186c0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e to prevent a den
186d0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a ial of service.*
186e0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c * attack. Devel
186f0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f opers might also
18700 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 want to use the
18710 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
18720 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 thorizer()].** i
18730 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 nterface to furt
18740 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 her control untr
18750 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 usted SQL. The
18760 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 size of the data
18770 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 base.** created
18780 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 by an untrusted
18790 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f script can be co
187a0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 ntained using th
187b0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 e.** [max_page_c
187c0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a ount] [PRAGMA]..
187d0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 **.** New run-ti
187e0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 me limit categor
187f0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ies may be added
18800 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
18810 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ses..**.** Requi
18820 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
18830 37 36 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48 762] [H12766] [H
18840 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 12769].*/.int sq
18850 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
18860 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
18870 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
18880 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
18890 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
188a0 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c ories {H12790} <
188b0 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f H12760>.** KEYWO
188c0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 RDS: {limit cate
188d0 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 gory} {limit cat
188e0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 egories}.**.** T
188f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
18900 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 efine various pe
18910 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 rformance limits
18920 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
18930 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 lowered at run-t
18940 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ime using [sqlit
18950 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 e3_limit()]..**
18960 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 The synopsis of
18970 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 the meanings of
18980 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 the various limi
18990 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f ts is shown belo
189a0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c w..** Additional
189b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
189c0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 available at [li
189d0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e mits | Limits in
189e0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 SQLite]..**.**
189f0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
18a00 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c TE_LIMIT_LENGTH<
18a10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
18a20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
18a30 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c any string or BL
18a40 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e OB or table row.
18a50 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 <dd>.**.** <dt>S
18a60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
18a70 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
18a80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
18a90 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 ength of an SQL
18aa0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a statement.</dd>.
18ab0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
18ac0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 _LIMIT_COLUMN</d
18ad0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
18ae0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
18af0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 columns in a tab
18b00 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 le definition or
18b10 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c in the.** resul
18b20 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
18b30 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d CT] or the maxim
18b40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c um number of col
18b50 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 umns in an index
18b60 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 .** or in an ORD
18b70 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 ER BY or GROUP B
18b80 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a Y clause.</dd>.*
18b90 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
18ba0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
18bb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
18bc0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
18bd0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 f the parse tree
18be0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 on any expressi
18bf0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
18c00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
18c10 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c COMPOUND_SELECT<
18c20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
18c30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
18c40 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d f terms in a com
18c50 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 pound SELECT sta
18c60 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a tement.</dd>.**.
18c70 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
18c80 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
18c90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
18ca0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
18cb0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
18cc0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
18cd0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
18ce0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
18cf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f SQL statement.</
18d00 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
18d10 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
18d20 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 ION_ARG</dt>.**
18d30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
18d40 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
18d50 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f nts on a functio
18d60 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
18d70 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 t>SQLITE_LIMIT_A
18d80 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 TTACHED</dt>.**
18d90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
18da0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 number of [ATTAC
18db0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 H | attached dat
18dc0 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a abases].</dd>.**
18dd0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
18de0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
18df0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a N_LENGTH</dt>.**
18e00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
18e10 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 length of the p
18e20 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 attern argument
18e30 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 to the [LIKE] or
18e40 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 .** [GLOB] opera
18e50 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tors.</dd>.**.**
18e60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
18e70 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
18e80 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 R</dt>.** <dd>Th
18e90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
18ea0 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e of variables in
18eb0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
18ec0 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 t that can.** be
18ed0 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 bound.</dd>.**
18ee0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
18ef0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 SQLITE_LIMIT_LE
18f00 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
18f10 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
18f20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 e SQLITE_LIMIT_S
18f30 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 QL_LENGTH
18f40 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
18f50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
18f60 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 COLUMN
18f70 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 2.#def
18f80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
18f90 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 _EXPR_DEPTH
18fa0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 3.#de
18fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
18fc0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
18fd0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 T 4.#d
18fe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
18ff0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 IT_VDBE_OP
19000 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
19010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
19020 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
19030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
19040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
19050 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 IMIT_ATTACHED
19060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 7
19070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19080 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
19090 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 RN_LENGTH
190a0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
190b0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
190c0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 NUMBER
190d0 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 9../*.** CAPI3R
190e0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
190f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b SQL Statement {
19100 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e H13010} <S10000>
19110 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
19120 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
19130 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 piler}.**.** To
19140 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 execute an SQL q
19150 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 uery, it must fi
19160 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 rst be compiled
19170 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 into a byte-code
19180 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e .** program usin
19190 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 g one of these r
191a0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
191b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
191c0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 t, "db", is a [d
191d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
191e0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f on] obtained fro
191f0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 m a.** prior suc
19200 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
19210 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
19220 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
19230 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c v2()] or.** [sql
19240 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 ite3_open16()].
19250 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f The database co
19260 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f nnection must no
19270 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 t have been clos
19280 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 ed..**.** The se
19290 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 cond argument, "
192a0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 zSql", is the st
192b0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
192c0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a mpiled, encoded.
192d0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 ** as either UTF
192e0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 -8 or UTF-16. T
192f0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
19300 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 re() and sqlite3
19310 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a _prepare_v2().**
19320 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 interfaces use
19330 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 UTF-8, and sqlit
19340 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 e3_prepare16() a
19350 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
19360 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 re16_v2().** use
19370 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 UTF-16..**.** I
19380 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 f the nByte argu
19390 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 ment is less tha
193a0 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 n zero, then zSq
193b0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 l is read up to
193c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 the.** first zer
193d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 o terminator. If
193e0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 nByte is non-ne
193f0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 gative, then it
19400 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a is the maximum.*
19410 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 * number of byt
19420 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 es read from zSq
19430 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 l. When nByte i
19440 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
19450 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 the.** zSql stri
19460 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 ng ends at eithe
19470 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 r the first '\00
19480 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 0' or '\u0000' c
19490 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 haracter or.** t
194a0 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 he nByte-th byte
194b0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
194c0 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 s first. If the
194d0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 caller knows.**
194e0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
194f0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
19500 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
19510 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c there is a smal
19520 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 l.** performance
19530 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 advantage to be
19540 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 gained by passi
19550 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 ng an nByte para
19560 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 meter that.** is
19570 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 equal to the nu
19580 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
19590 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
195a0 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f g <i>including</
195b0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 i>.** the nul-te
195c0 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a rminator bytes..
195d0 2a 2a 0a 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20 **.** If pzTail
195e0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
195f0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 *pzTail is made
19600 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 to point to the
19610 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 first byte.** p
19620 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ast the end of t
19630 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 he first SQL sta
19640 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 tement in zSql.
19650 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
19660 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 only.** compile
19670 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d the first statem
19680 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 ent in zSql, so
19690 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 *pzTail is left
196a0 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 pointing to.** w
196b0 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f hat remains unco
196c0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 mpiled..**.** *p
196d0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f pStmt is left po
196e0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 inting to a comp
196f0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 iled [prepared s
19700 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 tatement] that c
19710 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 an be.** execute
19720 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
19730 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 _step()]. If th
19740 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c ere is an error,
19750 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a *ppStmt is set.
19760 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 ** to NULL. If
19770 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
19780 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
19790 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
197a0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
197b0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
197c0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
197d0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
197e0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
197f0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
19800 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
19810 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
19820 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
19830 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
19840 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
19850 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
19860 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 d with it..** pp
19870 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 Stmt may not be
19880 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 NULL..**.** On s
19890 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f uccess, [SQLITE_
198a0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c OK] is returned,
198b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 otherwise an [e
198c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
198d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
198e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
198f0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 e_v2() and sqlit
19900 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
19910 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
19920 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 .** recommended
19930 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 for all new prog
19940 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c rams. The two ol
19950 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 der interfaces a
19960 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 re retained.** f
19970 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
19980 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 patibility, but
19990 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 their use is dis
199a0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 couraged..** In
199b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
199c0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 ces, the prepare
199d0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 d statement.** t
199e0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 hat is returned
199f0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 (the [sqlite3_st
19a00 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 mt] object) cont
19a10 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 ains a copy of t
19a20 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 he.** original S
19a30 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 QL text. This ca
19a40 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 uses the [sqlite
19a50 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 3_step()] interf
19a60 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 ace to.** behave
19a70 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 a differently i
19a80 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a n two ways:.**.*
19a90 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a * <ol>.** <li>.*
19aa0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
19ab0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 e schema changes
19ac0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 , instead of ret
19ad0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 urning [SQLITE_S
19ae0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 CHEMA] as it.**
19af0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 always used to d
19b00 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 o, [sqlite3_step
19b10 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 ()] will automat
19b20 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
19b30 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 the SQL.** stat
19b40 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f ement and try to
19b50 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 run it again.
19b60 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 If the schema ha
19b70 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 s changed in.**
19b80 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 a way that makes
19b90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e the statement n
19ba0 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 o longer valid,
19bb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
19bc0 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 will still.** r
19bd0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 eturn [SQLITE_SC
19be0 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 HEMA]. But unli
19bf0 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 ke the legacy be
19c00 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f havior, [SQLITE_
19c10 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f SCHEMA] is.** no
19c20 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e w a fatal error.
19c30 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 Calling [sqlit
19c40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
19c50 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 again will not
19c60 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f make the.** erro
19c70 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 r go away. Note
19c80 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 : use [sqlite3_e
19c90 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 rrmsg()] to find
19ca0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 the text.** of
19cb0 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f the parsing erro
19cc0 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 r that results i
19cd0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 n an [SQLITE_SCH
19ce0 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 EMA] return..**
19cf0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
19d00 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f .** When an erro
19d10 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 r occurs, [sqlit
19d20 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
19d30 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 return one of th
19d40 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 e detailed.** [e
19d50 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b rror codes] or [
19d60 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
19d70 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 odes]. The lega
19d80 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 cy behavior was
19d90 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 that.** [sqlite3
19da0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f _step()] would o
19db0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e nly return a gen
19dc0 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 eric [SQLITE_ERR
19dd0 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a OR] result code.
19de0 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 ** and you would
19df0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 have to make a
19e00 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b second call to [
19e10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
19e20 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 in order.** to
19e30 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 find the underly
19e40 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 ing cause of the
19e50 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 problem. With t
19e60 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a he "v2" prepare.
19e70 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 ** interfaces, t
19e80 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 he underlying re
19e90 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 ason for the err
19ea0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 or is returned i
19eb0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c mmediately..** <
19ec0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a /li>.** </ol>.**
19ed0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
19ee0 3a 0a 2a 2a 20 5b 48 31 33 30 31 31 5d 20 5b 48 :.** [H13011] [H
19ef0 31 33 30 31 32 5d 20 5b 48 31 33 30 31 33 5d 20 13012] [H13013]
19f00 5b 48 31 33 30 31 34 5d 20 5b 48 31 33 30 31 35 [H13014] [H13015
19f10 5d 20 5b 48 31 33 30 31 36 5d 20 5b 48 31 33 30 ] [H13016] [H130
19f20 31 39 5d 20 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 19] [H13021].**.
19f30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 */.int sqlite3_p
19f40 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 repare(. sqlite
19f50 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
19f60 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
19f70 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
19f80 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
19f90 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
19fa0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
19fb0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
19fc0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
19fd0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
19fe0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
19ff0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
1a000 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
1a010 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
1a020 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
1a030 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
1a040 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
1a050 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
1a060 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
1a070 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
1a080 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 3_prepare_v2(.
1a090 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1a0a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1a0b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
1a0c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
1a0d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
1a0e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 tatement, UTF-8
1a0f0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
1a100 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
1a110 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
1a120 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
1a130 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
1a140 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
1a150 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
1a160 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
1a170 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1a180 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
1a190 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
1a1a0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
1a1b0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
1a1c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1a1d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
1a1e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
1a1f0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
1a200 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
1a210 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
1a220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
1a230 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
1a240 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1a250 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1a260 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1a270 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1a280 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1a290 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1a2a0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1a2b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1a2c0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
1a2d0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1a2e0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1a2f0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1a300 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
1a310 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 epare16_v2(. sq
1a320 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1a330 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
1a340 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
1a350 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
1a360 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
1a370 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
1a380 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
1a390 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
1a3a0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
1a3b0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
1a3c0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
1a3d0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
1a3e0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
1a3f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
1a400 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
1a410 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
1a420 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
1a430 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
1a440 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a zSql */.);../*.*
1a450 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 * CAPI3REF: Retr
1a460 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 ieving Statement
1a470 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 SQL {H13100} <H
1a480 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 13000>.**.** Thi
1a490 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
1a4a0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 be used to retri
1a4b0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 eve a saved copy
1a4c0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c of the original
1a4d0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 .** SQL text use
1a4e0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 d to create a [p
1a4f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1a500 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 t] if that state
1a510 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 ment was.** comp
1a520 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 iled using eithe
1a530 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
1a540 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
1a550 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1a560 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 2()]..**.** Requ
1a570 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1a580 33 31 30 31 5d 20 5b 48 31 33 31 30 32 5d 20 5b 3101] [H13102] [
1a590 48 31 33 31 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 H13103].*/.const
1a5a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 char *sqlite3_s
1a5b0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ql(sqlite3_stmt
1a5c0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
1a5d0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 CAPI3REF: Dynami
1a5e0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 cally Typed Valu
1a5f0 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 e Object {H15000
1a600 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 } <S20200>.** KE
1a610 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 YWORDS: {protect
1a620 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1a630 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 } {unprotected s
1a640 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a qlite3_value}.**
1a650 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
1a660 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 the sqlite3_valu
1a670 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 e object to repr
1a680 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 esent all values
1a690 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
1a6a0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 stored in a data
1a6b0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 base table. SQLi
1a6c0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
1a6d0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 typing.** for th
1a6e0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 e values it stor
1a6f0 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 es. Values store
1a700 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c d in sqlite3_val
1a710 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 ue objects.** ca
1a720 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 n be integers, f
1a730 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
1a740 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 lues, strings, B
1a750 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a LOBs, or NULL..*
1a760 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f *.** An sqlite3_
1a770 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 value object may
1a780 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 be either "prot
1a790 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f ected" or "unpro
1a7a0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 tected"..** Some
1a7b0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 interfaces requ
1a7c0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 ire a protected
1a7d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 sqlite3_value.
1a7e0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 Other interfaces
1a7f0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 .** will accept
1a800 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 either a protect
1a810 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 ed or an unprote
1a820 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
1a830 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 ue..** Every int
1a840 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 erface that acce
1a850 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 pts sqlite3_valu
1a860 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 e arguments spec
1a870 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 ifies.** whether
1a880 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 or not it requi
1a890 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 res a protected
1a8a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
1a8b0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 *.** The terms "
1a8c0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 protected" and "
1a8d0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 unprotected" ref
1a8e0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 er to whether or
1a8f0 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 not.** a mutex
1a900 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 is held. A inte
1a910 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 rnal mutex is he
1a920 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 ld for a protect
1a930 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
1a940 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e lue object but n
1a950 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 o mutex is held
1a960 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 for an unprotect
1a970 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
1a980 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 lue object. If
1a990 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
1a9a0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d ed to be single-
1a9b0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 threaded.** (wit
1a9c0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 h [SQLITE_THREAD
1a9d0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 SAFE=0] and with
1a9e0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 [sqlite3_thread
1a9f0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e safe()] returnin
1aa00 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 g 0).** or if SQ
1aa10 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f Lite is run in o
1aa20 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 ne of reduced mu
1aa30 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 tex modes .** [S
1aa40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
1aa50 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 GLETHREAD] or [S
1aa60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
1aa70 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 TITHREAD].** the
1aa80 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 n there is no di
1aa90 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
1aaa0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
1aab0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
1aac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1aad0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 ects and they ca
1aae0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 n be used interc
1aaf0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 hangeably. Howe
1ab00 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 ver,.** for maxi
1ab10 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 mum code portabi
1ab20 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d lity it is recom
1ab30 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c mended that appl
1ab40 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c ications.** stil
1ab50 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 l make the disti
1ab60 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 nction between b
1ab70 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 etween protected
1ab80 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 and unprotected
1ab90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
1aba0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 e objects even w
1abb0 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 hen not strictly
1abc0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
1abd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c The sqlite3_val
1abe0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 ue objects that
1abf0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 are passed as pa
1ac00 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 rameters into th
1ac10 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
1ac20 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 ion of [applicat
1ac30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
1ac40 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 functions] are p
1ac50 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 rotected..** The
1ac60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1ac70 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
1ac80 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
1ac90 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
1aca0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a unprotected..**
1acb0 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c Unprotected sql
1acc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1acd0 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ts may only be u
1ace0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c sed with.** [sql
1acf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
1ad00 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
1ad10 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 3_bind_value()].
1ad20 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1ad30 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 _value_blob | sq
1ad40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
1ad50 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a ()] family of.**
1ad60 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 interfaces requ
1ad70 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 ire protected sq
1ad80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1ad90 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 cts..*/.typedef
1ada0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 struct Mem sqlit
1adb0 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a e3_value;../*.**
1adc0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 CAPI3REF: SQL F
1add0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 unction Context
1ade0 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20 Object {H16001}
1adf0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20200>.**.** T
1ae00 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 he context in wh
1ae10 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 ich an SQL funct
1ae20 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 ion executes is
1ae30 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 stored in an.**
1ae40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
1ae50 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 object. A point
1ae60 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 er to an sqlite3
1ae70 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a _context object.
1ae80 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 ** is always fir
1ae90 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
1aea0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
1aeb0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
1aec0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c ns]..** The appl
1aed0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
1aee0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
1aef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c lementation will
1af00 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f pass this.** po
1af10 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e inter through in
1af20 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c to calls to [sql
1af30 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 ite3_result_int
1af40 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 | sqlite3_result
1af50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1af60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
1af70 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f xt()], [sqlite3_
1af80 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a user_data()],.**
1af90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
1afa0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 t_db_handle()],
1afb0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 [sqlite3_get_aux
1afc0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f data()],.** and/
1afd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f or [sqlite3_set_
1afe0 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 auxdata()]..*/.t
1aff0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
1b000 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 lite3_context sq
1b010 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a lite3_context;..
1b020 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b030 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 Binding Values T
1b040 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 o Prepared State
1b050 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c ments {H13500} <
1b060 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S70300>.** KEYWO
1b070 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
1b080 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
1b090 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
1b0a0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
1b0b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
1b0c0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
1b0d0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
1b0e0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
1b0f0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c **.** In the SQL
1b100 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 strings input t
1b110 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
1b120 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 re_v2()] and its
1b130 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 variants,.** li
1b140 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 terals may be re
1b150 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 placed by a [par
1b160 61 6d 65 74 65 72 5d 20 69 6e 20 6f 6e 65 20 6f ameter] in one o
1b170 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a f these forms:.*
1b180 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
1b190 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e > ?.** <li> ?N
1b1a0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 NN.** <li> :VVV
1b1b0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a .** <li> @VVV.*
1b1c0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 * <li> $VVV.**
1b1d0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 </ul>.**.** In t
1b1e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 he parameter for
1b1f0 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e ms shown above N
1b200 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 NN is an integer
1b210 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 literal,.** and
1b220 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61 VVV is an alpha
1b230 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 -numeric paramet
1b240 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c er name. The val
1b250 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ues of these.**
1b260 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f parameters (also
1b270 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 called "host pa
1b280 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f rameter names" o
1b290 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 r "SQL parameter
1b2a0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 s").** can be se
1b2b0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 t using the sqli
1b2c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
1b2d0 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 tines defined he
1b2e0 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 re..**.** The fi
1b2f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
1b300 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
1b310 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 _*() routines is
1b320 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 always.** a poi
1b330 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c nter to the [sql
1b340 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 ite3_stmt] objec
1b350 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a t returned from.
1b360 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1b370 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 are_v2()] or its
1b380 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a variants..**.**
1b390 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
1b3a0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
1b3b0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 x of the SQL par
1b3c0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 ameter to be set
1b3d0 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 ..** The leftmos
1b3e0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 t SQL parameter
1b3f0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
1b400 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 1. When the sam
1b410 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 e named.** SQL p
1b420 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 arameter is used
1b430 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c more than once,
1b440 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
1b450 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 equent.** occurr
1b460 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 ences have the s
1b470 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 ame index as the
1b480 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 first occurrenc
1b490 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 e..** The index
1b4a0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 for named parame
1b4b0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b ters can be look
1b4c0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a ed up using the.
1b4d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1b4e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
1b4f0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 ()] API if desir
1b500 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a ed. The index.*
1b510 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 * for "?NNN" par
1b520 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 ameters is the v
1b530 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 alue of NNN..**
1b540 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 The NNN value mu
1b550 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 st be between 1
1b560 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 and the [sqlite3
1b570 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 _limit()].** par
1b580 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c ameter [SQLITE_L
1b590 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
1b5a0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 MBER] (default v
1b5b0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a alue: 999)..**.*
1b5c0 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 * The third argu
1b5d0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 ment is the valu
1b5e0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 e to bind to the
1b5f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
1b600 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 * In those routi
1b610 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
1b620 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
1b630 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
1b640 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
1b650 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
1b660 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
1b670 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
1b680 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
1b690 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
1b6a0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
1b6b0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
1b6c0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 characters..** I
1b6d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
1b6e0 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 ameter is negati
1b6f0 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f ve, the length o
1b700 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a f the string is.
1b710 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
1b720 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 bytes up to the
1b730 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
1b740 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 inator..**.** Th
1b750 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
1b760 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
1b770 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
1b780 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e _bind_text(), an
1b790 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e d.** sqlite3_bin
1b7a0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 d_text16() is a
1b7b0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
1b7c0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
1b7d0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
1b7e0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
1b7f0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
1b800 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 th it. If the fi
1b810 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
1b820 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
1b830 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
1b840 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
1b850 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
1b860 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
1b870 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
1b880 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
1b890 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
1b8a0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
1b8b0 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 * If the fifth a
1b8c0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 rgument has the
1b8d0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 value [SQLITE_TR
1b8e0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a ANSIENT], then.*
1b8f0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 * SQLite makes i
1b900 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
1b910 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 opy of the data
1b920 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 immediately, bef
1b930 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 ore.** the sqlit
1b940 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
1b950 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a ine returns..**.
1b960 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 ** The sqlite3_b
1b970 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 ind_zeroblob() r
1b980 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 outine binds a B
1b990 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 LOB of length N
1b9a0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 that.** is fille
1b9b0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 d with zeroes.
1b9c0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 A zeroblob uses
1b9d0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f a fixed amount o
1b9e0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 f memory.** (jus
1b9f0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 t an integer to
1ba00 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 hold its size) w
1ba10 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 hile it is being
1ba20 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a processed..** Z
1ba30 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 eroblobs are int
1ba40 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 ended to serve a
1ba50 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 s placeholders f
1ba60 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a or BLOBs whose.*
1ba70 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 * content is lat
1ba80 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 er written using
1ba90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
1baa0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 b_open | increme
1bab0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 ntal BLOB I/O] r
1bac0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 outines..** A ne
1bad0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 gative value for
1bae0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 the zeroblob re
1baf0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d sults in a zero-
1bb00 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a length BLOB..**.
1bb10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 ** The sqlite3_b
1bb20 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
1bb30 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
1bb40 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 after.** [sqlite
1bb50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1bb60 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 (and its variant
1bb70 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 s) or [sqlite3_r
1bb80 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 eset()] and.** b
1bb90 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 efore [sqlite3_s
1bba0 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 tep()]..** Bindi
1bbb0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 ngs are not clea
1bbc0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 red by the [sqli
1bbd0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 te3_reset()] rou
1bbe0 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 tine..** Unbound
1bbf0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
1bc00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e interpreted as N
1bc10 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ULL..**.** These
1bc20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1bc30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
1bc40 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 success or an er
1bc50 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 ror code if.** a
1bc60 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f nything goes wro
1bc70 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e ng. [SQLITE_RAN
1bc80 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 GE] is returned
1bc90 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
1bca0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 .** index is out
1bcb0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c of range. [SQL
1bcc0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 ITE_NOMEM] is re
1bcd0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 turned if malloc
1bce0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 () fails..** [SQ
1bcf0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 LITE_MISUSE] mig
1bd00 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 ht be returned i
1bd10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1bd20 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 are called on a
1bd30 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 .** virtual mach
1bd40 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20 ine that is the
1bd50 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 wrong state or w
1bd60 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 hich has already
1bd70 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e been finalized.
1bd80 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 .** Detection of
1bd90 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c misuse is unrel
1bda0 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 iable. Applicat
1bdb0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ions should not
1bdc0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c depend.** on SQL
1bdd0 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 ITE_MISUSE retur
1bde0 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 ns. SQLITE_MISU
1bdf0 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 SE is intended t
1be00 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 o indicate a.**
1be10 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e a logic error in
1be20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1be30 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
1be40 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
1be50 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 ht.** panic rath
1be60 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 er than return S
1be70 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
1be80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1be90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1bea0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a meter_count()],.
1beb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1bec0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
1bed0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
1bee0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1bef0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 index()]..**.**
1bf00 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1bf10 20 5b 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30 [H13506] [H1350
1bf20 39 5d 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33 9] [H13512] [H13
1bf30 35 31 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48 515] [H13518] [H
1bf40 31 33 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20 13521] [H13524]
1bf50 5b 48 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 [H13527].** [H13
1bf60 35 33 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48 530] [H13533] [H
1bf70 31 33 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20 13536] [H13539]
1bf80 5b 48 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35 [H13542] [H13545
1bf90 5d 20 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35 ] [H13548] [H135
1bfa0 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 51].**.*/.int sq
1bfb0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
1bfc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1bfd0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
1bfe0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 int n, void(*)(
1bff0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c void*));.int sql
1c000 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 ite3_bind_double
1c010 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1c020 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e int, double);.in
1c030 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 t sqlite3_bind_i
1c040 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
1c050 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 , int, int);.int
1c060 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
1c070 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
1c080 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
1c090 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 int64);.int sqli
1c0a0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 te3_bind_null(sq
1c0b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1c0c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
1c0d0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 ind_text(sqlite3
1c0e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
1c0f0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c st char*, int n,
1c100 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
1c110 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
1c120 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 nd_text16(sqlite
1c130 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
1c140 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
1c150 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
1c160 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1c170 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f d_value(sqlite3_
1c180 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
1c190 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t sqlite3_value*
1c1a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
1c1b0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c ind_zeroblob(sql
1c1c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1c1d0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int n);../*.**
1c1e0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
1c1f0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 Of SQL Paramete
1c200 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 rs {H13600} <S70
1c210 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 300>.**.** This
1c220 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 routine can be u
1c230 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 sed to find the
1c240 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 number of [SQL p
1c250 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e arameters].** in
1c260 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1c270 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 tement]. SQL pa
1c280 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b rameters are tok
1c290 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f ens of the.** fo
1c2a0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 rm "?", "?NNN",
1c2b0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 ":AAA", "$AAA",
1c2c0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 or "@AAA" that s
1c2d0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 erve as.** place
1c2e0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 holders for valu
1c2f0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c es that are [sql
1c300 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
1c310 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 bound].** to th
1c320 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 e parameters at
1c330 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a a later time..**
1c340 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
1c350 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e actually return
1c360 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
1c370 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 he largest (righ
1c380 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 tmost).** parame
1c390 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 ter. For all for
1c3a0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 ms except ?NNN,
1c3b0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 this will corres
1c3c0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e pond to the.** n
1c3d0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 umber of unique
1c3e0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 parameters. If
1c3f0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
1c400 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c e ?NNN are used,
1c410 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 .** there may be
1c420 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 gaps in the lis
1c430 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 t..**.** See als
1c440 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
1c450 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
1c460 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
1c470 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1c480 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a r_name()], and.*
1c490 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
1c4a0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
1c4b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
1c4c0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 ements:.** [H136
1c4d0 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 01].*/.int sqlit
1c4e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1c4f0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f r_count(sqlite3_
1c500 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
1c510 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
1c520 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 A Host Paramete
1c530 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 r {H13620} <S703
1c540 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
1c550 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
1c560 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
1c570 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 name of the n-th
1c580 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 .** [SQL paramet
1c590 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 er] in a [prepar
1c5a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
1c5b0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 * SQL parameters
1c5c0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e of the form "?N
1c5d0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
1c5e0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
1c5f0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 ".** have a name
1c600 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
1c610 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 ring "?NNN" or "
1c620 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
1c630 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 or "$AAA".** res
1c640 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e pectively..** In
1c650 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
1c660 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 e initial ":" or
1c670 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 "$" or "@" or "
1c680 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 ?".** is include
1c690 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
1c6a0 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 name..** Parame
1c6b0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
1c6c0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 "?" without a f
1c6d0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 ollowing integer
1c6e0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a have no name.**
1c6f0 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 and are also re
1c700 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e ferred to as "an
1c710 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
1c720 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 rs"..**.** The f
1c730 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 irst host parame
1c740 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 ter has an index
1c750 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a of 1, not 0..**
1c760 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 .** If the value
1c770 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e n is out of ran
1c780 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 ge or if the n-t
1c790 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
1c7a0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
1c7b0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
1c7c0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 d. The returned
1c7d0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c string is.** al
1c7e0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e ways in UTF-8 en
1c7f0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 coding even if t
1c800 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 he named paramet
1c810 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e er was.** origin
1c820 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 ally specified a
1c830 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c s UTF-16 in [sql
1c840 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
1c850 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
1c860 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1c870 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1c880 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
1c890 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
1c8a0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
1c8b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1c8c0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
1c8d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
1c8e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
1c8f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
1c900 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 ements:.** [H136
1c910 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 21].*/.const cha
1c920 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f r *sqlite3_bind_
1c930 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 parameter_name(s
1c940 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1c950 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
1c960 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 REF: Index Of A
1c970 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 Parameter With A
1c980 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 Given Name {H13
1c990 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 640} <S70300>.**
1c9a0 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 .** Return the i
1c9b0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 ndex of an SQL p
1c9c0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 arameter given i
1c9d0 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a ts name. The.**
1c9e0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 index value ret
1c9f0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c urned is suitabl
1ca00 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 e for use as the
1ca10 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d second.** param
1ca20 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
1ca30 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
1ca40 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a e3_bind()]. A z
1ca50 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ero.** is return
1ca60 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e ed if no matchin
1ca70 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 g parameter is f
1ca80 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d ound. The param
1ca90 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 eter.** name mus
1caa0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 t be given in UT
1cab0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 F-8 even if the
1cac0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
1cad0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 nt.** was prepar
1cae0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 ed from UTF-16 t
1caf0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ext using [sqlit
1cb00 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1cb10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
1cb20 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
1cb30 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
1cb40 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
1cb50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1cb60 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
1cb70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1cb80 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
1cb90 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 x()]..**.** Requ
1cba0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1cbb0 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 3641].*/.int sql
1cbc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1cbd0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 ter_index(sqlite
1cbe0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 3_stmt*, const c
1cbf0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a har *zName);../*
1cc00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
1cc10 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 set All Bindings
1cc20 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 On A Prepared S
1cc30 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 tatement {H13660
1cc40 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
1cc50 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 Contrary to the
1cc60 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 intuition of ma
1cc70 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ny, [sqlite3_res
1cc80 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 et()] does not r
1cc90 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c eset.** the [sql
1cca0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
1ccb0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 bindings] on a
1ccc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1ccd0 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 ent]..** Use thi
1cce0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 s routine to res
1ccf0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 et all host para
1cd00 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a meters to NULL..
1cd10 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1cd20 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a ts:.** [H13661].
1cd30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
1cd40 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 lear_bindings(sq
1cd50 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
1cd60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
1cd70 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 umber Of Columns
1cd80 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
1cd90 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 {H13710} <S1070
1cda0 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 0>.**.** Return
1cdb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
1cdc0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
1cdd0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 ult set returned
1cde0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 by the.** [prep
1cdf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
1ce00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
1ce10 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 turns 0 if pStmt
1ce20 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 is an SQL.** st
1ce30 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 atement that doe
1ce40 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 s not return dat
1ce50 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 a (for example a
1ce60 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a n [UPDATE])..**.
1ce70 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1ce80 0a 2a 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a .** [H13711].*/.
1ce90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
1cea0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 mn_count(sqlite3
1ceb0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
1cec0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1ced0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 Column Names In
1cee0 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 A Result Set {H1
1cef0 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3720} <S10700>.*
1cf00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1cf10 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e nes return the n
1cf20 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 ame assigned to
1cf30 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c a particular col
1cf40 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 umn.** in the re
1cf50 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
1cf60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1cf70 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 . The sqlite3_c
1cf80 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 olumn_name().**
1cf90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
1cfa0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
1cfb0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1cfc0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
1cfd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
1cfe0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 umn_name16() ret
1cff0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1d000 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
1d010 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
1d020 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 ring. The first
1d030 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1d040 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
1d050 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 ement].** that i
1d060 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 mplements the [S
1d070 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1d080 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 . The second par
1d090 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
1d0a0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 column number.
1d0b0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f The leftmost co
1d0c0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 lumn is number 0
1d0d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 ..**.** The retu
1d0e0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e rned string poin
1d0f0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ter is valid unt
1d100 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 il either the [p
1d110 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1d120 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 t].** is destroy
1d130 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
1d140 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
1d150 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c til the next cal
1d160 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
1d170 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 column_name() or
1d180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
1d190 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 name16() on the
1d1a0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a same column..**.
1d1b0 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 ** If sqlite3_ma
1d1c0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 lloc() fails dur
1d1d0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 ing the processi
1d1e0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 ng of either rou
1d1f0 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 tine.** (for exa
1d200 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f mple during a co
1d210 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 nversion from UT
1d220 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 F-8 to UTF-16) t
1d230 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f hen a.** NULL po
1d240 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
1d250 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d d..**.** The nam
1d260 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f e of a result co
1d270 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 lumn is the valu
1d280 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c e of the "AS" cl
1d290 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 ause for.** that
1d2a0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 column, if ther
1d2b0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 e is an AS claus
1d2c0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 e. If there is
1d2d0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 no AS clause.**
1d2e0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 then the name of
1d2f0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 the column is u
1d300 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d nspecified and m
1d310 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a ay change from.*
1d320 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 * one release of
1d330 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e SQLite to the n
1d340 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ext..**.** Requi
1d350 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 rements:.** [H13
1d360 37 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48 721] [H13723] [H
1d370 31 33 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20 13724] [H13725]
1d380 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37 [H13726] [H13727
1d390 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ].*/.const char
1d3a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1d3b0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
1d3c0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 t*, int N);.cons
1d3d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1d3e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 column_name16(sq
1d3f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1d400 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 N);../*.** CAPI
1d410 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 3REF: Source Of
1d420 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 Data In A Query
1d430 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 Result {H13740}
1d440 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S10700>.**.** T
1d450 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 hese routines pr
1d460 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f ovide a means to
1d470 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 determine what
1d480 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a column of what.*
1d490 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 * table in which
1d4a0 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 database a resu
1d4b0 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d lt of a [SELECT]
1d4c0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 statement comes
1d4d0 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 from..** The na
1d4e0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
1d4f0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 se or table or c
1d500 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 olumn can be ret
1d510 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 urned as.** eith
1d520 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 er a UTF-8 or UT
1d530 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 F-16 string. Th
1d540 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 e _database_ rou
1d550 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tines return.**
1d560 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
1d570 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 e, the _table_ r
1d580 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
1d590 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 he table name, a
1d5a0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e nd.** the origin
1d5b0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
1d5c0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d n the column nam
1d5d0 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e e..** The return
1d5e0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c ed string is val
1d5f0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 id until the [pr
1d600 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1d610 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a ] is destroyed.*
1d620 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
1d630 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
1d640 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 until the same i
1d650 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 nformation is re
1d660 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e quested.** again
1d670 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 in a different
1d680 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 encoding..**.**
1d690 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e The names return
1d6a0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 ed are the origi
1d6b0 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e nal un-aliased n
1d6c0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 ames of the.** d
1d6d0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 atabase, table,
1d6e0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a and column..**.*
1d6f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
1d700 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c ment to the foll
1d710 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 owing calls is a
1d720 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1d730 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 ment]..** These
1d740 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
1d750 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
1d760 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d ut the Nth colum
1d770 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a n returned by.**
1d780 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 the statement,
1d790 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
1d7a0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 econd function a
1d7b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 rgument..**.** I
1d7c0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
1d7d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
1d7e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e statement is an
1d7f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a expression or.*
1d800 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 * subquery and i
1d810 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 s not a column v
1d820 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f alue, then all o
1d830 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
1d840 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c s return.** NULL
1d850 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
1d860 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 might also retu
1d870 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d rn NULL if a mem
1d880 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
1d890 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 rror.** occurs.
1d8a0 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 Otherwise, they
1d8b0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
1d8c0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 of the attached
1d8d0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
1d8e0 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 .** and column t
1d8f0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 hat query result
1d900 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 column was extr
1d910 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a acted from..**.*
1d920 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 * As with all ot
1d930 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c her SQLite APIs,
1d940 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 those postfixed
1d950 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 with "16" retur
1d960 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f n.** UTF-16 enco
1d970 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 ded strings, the
1d980 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 other functions
1d990 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b return UTF-8. {
1d9a0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 END}.**.** These
1d9b0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 APIs are only a
1d9c0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 vailable if the
1d9d0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 library was comp
1d9e0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a iled with the.**
1d9f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
1da00 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d COLUMN_METADATA]
1da10 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C-preprocessor
1da20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
1da30 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a **.** {A13751}.*
1da40 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
1da50 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
1da60 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 e or more of the
1da70 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 se routines agai
1da80 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 nst the same.**
1da90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1daa0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 nt and column at
1dab0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
1dac0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
1dad0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 are.** undefined
1dae0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1daf0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 ents:.** [H13741
1db00 5d 20 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37 ] [H13742] [H137
1db10 34 33 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31 43] [H13744] [H1
1db20 33 37 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b 3745] [H13746] [
1db30 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 H13748].**.** If
1db40 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
1db50 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
1db60 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 more.** [sqlite
1db70 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
1db80 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 e_name | column
1db90 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 metadata interfa
1dba0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ces].** for the
1dbb0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
1dbc0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 tatement] and re
1dbd0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 sult column.** a
1dbe0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
1dbf0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
1dc00 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
1dc10 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
1dc20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
1dc30 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 tabase_name(sqli
1dc40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
1dc50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
1dc60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
1dc70 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ase_name16(sqlit
1dc80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
1dc90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1dca0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
1dcb0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
1dcc0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
1dcd0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
1dce0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 umn_table_name16
1dcf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
1dd00 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 nt);.const char
1dd10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1dd20 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 origin_name(sqli
1dd30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
1dd40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
1dd50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
1dd60 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
1dd70 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
1dd80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
1dd90 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 clared Datatype
1dda0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c Of A Query Resul
1ddb0 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 t {H13760} <S107
1ddc0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 00>.**.** The fi
1ddd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
1dde0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1ddf0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 tement]..** If t
1de00 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 his statement is
1de10 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
1de20 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 ement and the Nt
1de30 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a h column of the.
1de40 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 ** returned resu
1de50 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b lt set of that [
1de60 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 SELECT] is a tab
1de70 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 le column (not a
1de80 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
1de90 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 or subquery) the
1dea0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 n the declared t
1deb0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ype of the table
1dec0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 .** column is re
1ded0 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 turned. If the
1dee0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
1def0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 e result set is
1df00 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
1df10 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 or subquery, th
1df20 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
1df30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
1df40 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 * The returned s
1df50 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 tring is always
1df60 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b UTF-8 encoded. {
1df70 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 END}.**.** For e
1df80 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 xample, given th
1df90 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
1dfa0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 a:.**.** CREATE
1dfb0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 TABLE t1(c1 VARI
1dfc0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 ANT);.**.** and
1dfd0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
1dfe0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
1dff0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 mpiled:.**.** SE
1e000 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 LECT c1 + 1, c1
1e010 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 FROM t1;.**.** t
1e020 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c his routine woul
1e030 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 d return the str
1e040 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f ing "VARIANT" fo
1e050 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 r the second res
1e060 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 ult.** column (i
1e070 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c ==1), and a NULL
1e080 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
1e090 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f first result co
1e0a0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a lumn (i==0)..**.
1e0b0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 ** SQLite uses d
1e0c0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 ynamic run-time
1e0d0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 typing. So just
1e0e0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d because a colum
1e0f0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 n.** is declared
1e100 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 to contain a pa
1e110 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f rticular type do
1e120 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 es not mean that
1e130 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f the.** data sto
1e140 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 red in that colu
1e150 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 mn is of the dec
1e160 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c lared type. SQL
1e170 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 ite is.** strong
1e180 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 ly typed, but th
1e190 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 e typing is dyna
1e1a0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 mic not static.
1e1b0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f Type.** is asso
1e1c0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 ciated with indi
1e1d0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e vidual values, n
1e1e0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 ot with the cont
1e1f0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 ainers.** used t
1e200 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c o hold those val
1e210 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ues..**.** Requi
1e220 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 rements:.** [H13
1e230 37 36 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48 761] [H13762] [H
1e240 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 13763].*/.const
1e250 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
1e260 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 lumn_decltype(sq
1e270 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
1e280 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
1e290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
1e2a0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f ltype16(sqlite3_
1e2b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
1e2c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 ** CAPI3REF: Eva
1e2d0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
1e2e0 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 tement {H13200}
1e2f0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 <S10000>.**.** A
1e300 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 fter a [prepared
1e310 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 statement] has
1e320 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 been prepared us
1e330 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 ing either.** [s
1e340 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1e350 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1e360 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1e370 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c or one of the l
1e380 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
1e390 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
1e3a0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 pare()] or [sqli
1e3b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
1e3c0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a , this function.
1e3d0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ** must be calle
1e3e0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
1e3f0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 mes to evaluate
1e400 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a the statement..*
1e410 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 *.** The details
1e420 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 of the behavior
1e430 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
1e440 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 step() interface
1e450 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 depend.** on wh
1e460 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d ether the statem
1e470 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 ent was prepared
1e480 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 using the newer
1e490 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a "v2" interface.
1e4a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1e4b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
1e4c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1e4d0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c _v2()] or the ol
1e4e0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e der legacy.** in
1e4f0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 terface [sqlite3
1e500 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
1e510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e520 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 16()]. The use
1e530 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 of the.** new "v
1e540 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
1e550 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
1e560 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
1e570 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a but the legacy.
1e580 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c ** interface wil
1e590 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 l continue to be
1e5a0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a supported..**.*
1e5b0 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 * In the legacy
1e5c0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
1e5d0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
1e5e0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
1e5f0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
1e600 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
1e610 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
1e620 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
1e630 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
1e640 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 With the "v2" i
1e650 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
1e660 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 the other [resu
1e670 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 lt codes] or.**
1e680 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
1e690 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 codes] might be
1e6a0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c returned as wel
1e6b0 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 l..**.** [SQLITE
1e6c0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 _BUSY] means tha
1e6d0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 t the database e
1e6e0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 ngine was unable
1e6f0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a to acquire the.
1e700 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b ** database lock
1e710 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f s it needs to do
1e720 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 its job. If th
1e730 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
1e740 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 [COMMIT].** or
1e750 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f occurs outside o
1e760 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 f an explicit tr
1e770 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
1e780 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 you can retry th
1e790 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 e.** statement.
1e7a0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
1e7b0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d t is not a [COMM
1e7c0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 IT] and occurs w
1e7d0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 ithin a.** expli
1e7e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 cit transaction
1e7f0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 then you should
1e800 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 rollback the tra
1e810 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a nsaction before.
1e820 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a ** continuing..*
1e830 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e *.** [SQLITE_DON
1e840 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
1e850 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
1e860 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
1e870 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
1e880 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
1e890 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
1e8a0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
1e8b0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
1e8c0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
1e8d0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
1e8e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
1e8f0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
1e900 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
1e910 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
1e920 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
1e930 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
1e940 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
1e950 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
1e960 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 ny data, then [S
1e970 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 QLITE_ROW].** is
1e980 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 returned each t
1e990 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 ime a new row of
1e9a0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 data is ready f
1e9b0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 or processing by
1e9c0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 the.** caller.
1e9d0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 The values may b
1e9e0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 e accessed using
1e9f0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 the [column acc
1ea00 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a ess functions]..
1ea10 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
1ea20 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 ) is called agai
1ea30 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 n to retrieve th
1ea40 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 e next row of da
1ea50 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ta..**.** [SQLIT
1ea60 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
1ea70 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
1ea80 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
1ea90 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
1eaa0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
1eab0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
1eac0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
1ead0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
1eae0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
1eaf0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
1eb00 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
1eb10 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
1eb20 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
1eb30 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 With the legacy
1eb40 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 interface, a mor
1eb50 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
1eb60 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 code (for examp
1eb70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 le,.** [SQLITE_I
1eb80 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 NTERRUPT], [SQLI
1eb90 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c TE_SCHEMA], [SQL
1eba0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e ITE_CORRUPT], an
1ebb0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 d so forth).** c
1ebc0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 an be obtained b
1ebd0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
1ebe0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 e3_reset()] on t
1ebf0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
1ec00 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 statement]. In
1ec10 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
1ec20 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
1ec30 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
1ec40 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
1ec50 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
1ec60 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
1ec70 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
1ec80 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
1ec90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
1eca0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
1ecb0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
1ecc0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
1ecd0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
1ece0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
1ecf0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
1ed00 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
1ed10 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
1ed20 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
1ed30 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
1ed40 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
1ed50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
1ed60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
1ed70 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
1ed80 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
1ed90 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
1eda0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
1edb0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
1edc0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
1edd0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
1ede0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
1edf0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 ..**.** <b>Goofy
1ee00 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 Interface Alert
1ee10 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 :</b> In the leg
1ee20 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
1ee30 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 he sqlite3_step(
1ee40 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 ).** API always
1ee50 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 returns a generi
1ee60 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 c error code, [S
1ee70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f QLITE_ERROR], fo
1ee80 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 llowing any.** e
1ee90 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 rror other than
1eea0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e [SQLITE_BUSY] an
1eeb0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 d [SQLITE_MISUSE
1eec0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c ]. You must cal
1eed0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 l.** [sqlite3_re
1eee0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
1eef0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
1ef00 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 n order to find
1ef10 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 one of the.** sp
1ef20 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f ecific [error co
1ef30 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 des] that better
1ef40 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
1ef50 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 rror..** We admi
1ef60 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 t that this is a
1ef70 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 goofy design.
1ef80 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 The problem has
1ef90 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 been fixed.** wi
1efa0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
1efb0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 rface. If you p
1efc0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f repare all of yo
1efd0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ur SQL statement
1efe0 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 s.** using eithe
1eff0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
1f000 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
1f010 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1f020 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 2()] instead.**
1f030 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 of the legacy [s
1f040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
1f050 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
1f060 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 repare16()] inte
1f070 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 rfaces,.** then
1f080 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
1f090 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 c [error codes]
1f0a0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 are returned dir
1f0b0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 ectly.** by sqli
1f0c0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 te3_step(). The
1f0d0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 use of the "v2"
1f0e0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
1f0f0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a commended..**.**
1f100 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1f110 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33 * [H13202] [H153
1f120 30 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31 04] [H15306] [H1
1f130 35 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 5308] [H15310].*
1f140 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 /.int sqlite3_st
1f150 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ep(sqlite3_stmt*
1f160 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1f170 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f EF: Number of co
1f180 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c lumns in a resul
1f190 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c t set {H13770} <
1f1a0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 S10700>.**.** Re
1f1b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
1f1c0 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 of values in th
1f1d0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 e current row of
1f1e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e the result set.
1f1f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1f200 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d nts:.** [H13771]
1f210 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 [H13772].*/.int
1f220 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
1f230 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
1f240 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
1f250 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
1f260 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
1f270 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 {H10265} <S1011
1f280 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 0><S10120>.** KE
1f290 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 YWORDS: SQLITE_T
1f2a0 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 EXT.**.** {H1026
1f2b0 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6} Every value i
1f2c0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 n SQLite has one
1f2d0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 of five fundame
1f2e0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a ntal datatypes:.
1f2f0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
1f300 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 i> 64-bit signed
1f310 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e integer.** <li>
1f320 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 64-bit IEEE flo
1f330 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
1f340 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e er.** <li> strin
1f350 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a g.** <li> BLOB.*
1f360 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c * <li> NULL.** <
1f370 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a /ul> {END}.**.**
1f380 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
1f390 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 are codes for e
1f3a0 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 ach of those typ
1f3b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 es..**.** Note t
1f3c0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hat the SQLITE_T
1f3d0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 EXT constant was
1f3e0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 also used in SQ
1f3f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a Lite version 2.*
1f400 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 * for a complete
1f410 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 ly different mea
1f420 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 ning. Software
1f430 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e that links again
1f440 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 st both.** SQLit
1f450 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 e version 2 and
1f460 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
1f470 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 should use SQLI
1f480 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a TE3_TEXT, not.**
1f490 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f SQLITE_TEXT..*/
1f4a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f4b0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 INTEGER 1.#defi
1f4c0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 ne SQLITE_FLOAT
1f4d0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
1f4e0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 ITE_BLOB 4.#
1f4f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 define SQLITE_NU
1f500 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 LL 5.#ifdef
1f510 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e SQLITE_TEXT.# un
1f520 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
1f530 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 #else.# define S
1f540 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 QLITE_TEXT 3
1f550 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 .#endif.#define
1f560 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 SQLITE3_TEXT
1f570 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3../*.** CAPI3R
1f580 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 EF: Result Value
1f590 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b s From A Query {
1f5a0 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e H13800} <S10700>
1f5b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 .** KEYWORDS: {c
1f5c0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
1f5d0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 ctions}.**.** Th
1f5e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ese routines for
1f5f0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 m the "result se
1f600 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 t query" interfa
1f610 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ce..**.** These
1f620 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1f630 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
1f640 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d t a single colum
1f650 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
1f660 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f .** result row o
1f670 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 f a query. In e
1f680 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 very case the fi
1f690 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
1f6a0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
1f6b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
1f6c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 atement] that is
1f6d0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 being evaluated
1f6e0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
1f6f0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 tmt*].** that wa
1f700 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 s returned from
1f710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f720 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
1f730 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a its variants).*
1f740 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 * and the second
1f750 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
1f760 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f index of the co
1f770 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 lumn for which i
1f780 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 nformation.** sh
1f790 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
1f7a0 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 . The leftmost
1f7b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
1f7c0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 sult set has the
1f7d0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 index 0..**.**
1f7e0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
1f7f0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 ment does not cu
1f800 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f rrently point to
1f810 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 a valid row, or
1f820 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d if the.** colum
1f830 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f n index is out o
1f840 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 f range, the res
1f850 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
1f860 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
1f870 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 nes may only be
1f880 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
1f890 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
1f8a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
1f8b0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
1f8c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
1f8d0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a ] and neither.**
1f8e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1f8f0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f )] nor [sqlite3_
1f900 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 finalize()] have
1f910 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 been called sub
1f920 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 sequently..** If
1f930 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
1f940 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
1f950 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 d after [sqlite3
1f960 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
1f970 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1f980 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 e()] or after [s
1f990 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
1f9a0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 as returned.** s
1f9b0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
1f9c0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
1f9d0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 , the results ar
1f9e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 e undefined..**
1f9f0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 If [sqlite3_step
1fa00 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1fa10 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
1fa20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
1fa30 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 .** are called f
1fa40 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 rom a different
1fa50 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 thread while any
1fa60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
1fa70 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e es.** are pendin
1fa80 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 g, then the resu
1fa90 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
1faa0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
1fab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
1fac0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
1fad0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ns the.** [SQLIT
1fae0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
1faf0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 type code] for t
1fb00 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 he initial data
1fb10 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 type.** of the r
1fb20 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 esult column. T
1fb30 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 he returned valu
1fb40 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c e is one of [SQL
1fb50 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a ITE_INTEGER],.**
1fb60 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
1fb70 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
1fb80 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f [SQLITE_BLOB], o
1fb90 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e r [SQLITE_NULL].
1fba0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 The value.** r
1fbb0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1fbc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
1fbd0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 is only meaning
1fbe0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a ful if no type.*
1fbf0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 * conversions ha
1fc00 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 ve occurred as d
1fc10 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 escribed below.
1fc20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f After a type co
1fc30 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 nversion,.** the
1fc40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1fc50 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
1fc60 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 n_type() is unde
1fc70 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a fined. Future.*
1fc80 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 * versions of SQ
1fc90 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 Lite may change
1fca0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
1fcb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
1fcc0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 ype().** followi
1fcd0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 ng a type conver
1fce0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 sion..**.** If t
1fcf0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 he result is a B
1fd00 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 LOB or UTF-8 str
1fd10 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c ing then the sql
1fd20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
1fd30 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 s().** routine r
1fd40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
1fd50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
1fd60 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
1fd70 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 g..** If the res
1fd80 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 ult is a UTF-16
1fd90 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c string, then sql
1fda0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
1fdb0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 s() converts.**
1fdc0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
1fdd0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 F-8 and then ret
1fde0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
1fdf0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 of bytes..** If
1fe00 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
1fe10 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
1fe20 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
1fe30 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a n_bytes() uses.*
1fe40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 * [sqlite3_snpri
1fe50 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 ntf()] to conver
1fe60 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 t that value to
1fe70 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 a UTF-8 string a
1fe80 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 nd returns.** th
1fe90 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
1fea0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 s in that string
1feb0 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 ..** The value r
1fec0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 eturned does not
1fed0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 include the zer
1fee0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 o terminator at
1fef0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 the end.** of th
1ff00 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 e string. For c
1ff10 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 larity: the valu
1ff20 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 e returned is th
1ff30 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 e number of.** b
1ff40 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
1ff50 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
1ff60 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
1ff70 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 ..**.** Strings
1ff80 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1ff90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
1ffa0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f ) and sqlite3_co
1ffb0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a lumn_text16(),.*
1ffc0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 * even empty str
1ffd0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 ings, are always
1ffe0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 zero terminated
1fff0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a . The return.**
20000 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
20010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
20020 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
20030 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 gth BLOB is an a
20040 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e rbitrary.** poin
20050 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 ter, possibly ev
20060 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
20070 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
20080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
20090 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 s16() routine is
200a0 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 similar to sqli
200b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
200c0 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 ().** but leaves
200d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 the result in U
200e0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 TF-16 in native
200f0 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 byte order inste
20100 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 ad of UTF-8..**
20110 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 The zero termina
20120 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 tor is not inclu
20130 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e ded in this coun
20140 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a t..**.** The obj
20150 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 ect returned by
20160 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
20170 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a value()] is an.*
20180 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
20190 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
201a0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 ject. An unprot
201b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
201c0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 lue object.** ma
201d0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
201e0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e ith [sqlite3_bin
201f0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
20200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
20210 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
20220 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
20230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
20240 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
20250 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
20260 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
20270 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
20280 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
20290 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
202a0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
202b0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
202c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
202d0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
202e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
202f0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 bytes()], then t
20300 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
20310 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
20320 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
20330 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 ttempt to conver
20340 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 t the value wher
20350 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 e appropriate.
20360 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
20370 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 if the internal
20380 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 representation i
20390 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 s FLOAT and a te
203a0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 xt result.** is
203b0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 requested, [sqli
203c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
203d0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c is used internal
203e0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 ly to perform th
203f0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e.** conversion
20400 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
20410 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 The following ta
20420 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 ble details the
20430 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 conversions.** t
20440 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a hat are applied:
20450 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
20460 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f te>.** <table bo
20470 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 rder="1">.** <tr
20480 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 ><th> Internal<b
20490 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 r>Type <th> Requ
204a0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 ested<br>Type <t
204b0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a h> Conversion.*
204c0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e *.** <tr><td> N
204d0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 ULL <td> INTE
204e0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c GER <td> Resul
204f0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 t is 0.** <tr><t
20500 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
20510 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
20520 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a Result is 0.0.**
20530 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
20540 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
20550 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
20560 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
20570 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
20580 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
20590 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
205a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
205b0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
205c0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 R <td> FLOAT
205d0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 <td> Convert f
205e0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 rom integer to f
205f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
20600 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
20610 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
20620 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
20630 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 the integer.**
20640 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
20650 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
20660 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e <td> Same as IN
20670 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c TEGER->TEXT.** <
20680 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
20690 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
206a0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
206b0 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 m float to integ
206c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
206d0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 FLOAT <td> T
206e0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
206f0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
20700 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e he float.** <tr>
20710 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
20720 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
20730 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d > Same as FLOAT-
20740 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
20750 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
20760 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 INTEGER <td> U
20770 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 se atoi().** <tr
20780 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
20790 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
207a0 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a d> Use atof().**
207b0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
207c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
207d0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 <td> No change
207e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
207f0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OB <td> INTEG
20800 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 ER <td> Conver
20810 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 t to TEXT then u
20820 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 se atoi().** <tr
20830 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
20840 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
20850 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 d> Convert to TE
20860 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 XT then use atof
20870 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
20880 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 BLOB <td> T
20890 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 EXT <td> Add
208a0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f a zero terminato
208b0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c r if needed.** <
208c0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f /table>.** </blo
208d0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
208e0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d he table above m
208f0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 akes reference t
20900 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 o standard C lib
20910 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 rary functions a
20920 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f toi().** and ato
20930 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 f(). SQLite doe
20940 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 s not really use
20950 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
20960 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a . It has its.**
20970 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 own equivalent
20980 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 internal routine
20990 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 s. The atoi() a
209a0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 nd atof() names
209b0 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 are.** used in t
209c0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 he table for bre
209d0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 vity and because
209e0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 they are famili
209f0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 ar to most.** C
20a00 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a programmers..**.
20a10 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 ** Note that whe
20a20 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f n type conversio
20a30 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 ns occur, pointe
20a40 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 rs returned by p
20a50 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f rior.** calls to
20a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
20a70 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
20a80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 column_text(), a
20a90 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 nd/or.** sqlite3
20aa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
20ab0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 may be invalida
20ac0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e ted..** Type con
20ad0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 versions and poi
20ae0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f nter invalidatio
20af0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ns might occur.*
20b00 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 * in the followi
20b10 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 ng cases:.**.**
20b20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
20b30 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
20b40 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 is a BLOB and s
20b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
20b60 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 xt() or.**
20b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
20b80 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
20b90 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 d. A zero-termi
20ba0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 nator might.**
20bb0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
20bc0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
20bd0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e ng.</li>.** <li>
20be0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
20bf0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 tent is UTF-8 te
20c00 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
20c10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
20c20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
20c30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
20c40 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
20c50 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
20c60 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
20c70 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c to UTF-16.<
20c80 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
20c90 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
20ca0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 is UTF-16 text
20cb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
20cc0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
20cd0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
20ce0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 lumn_text() is c
20cf0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
20d00 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
20d10 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
20d20 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-8.</li>.**
20d30 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 </ul>.**.** Conv
20d40 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
20d50 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
20d60 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
20d70 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
20d80 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
20d90 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
20da0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
20db0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
20dc0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
20dd0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
20de0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f prior pointer po
20df0 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 ints to will hav
20e00 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
20e10 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
20e20 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
20e30 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
20e40 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
20e50 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
20e60 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 mes they.** are
20e70 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 not possible and
20e80 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 in those cases
20e90 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 prior pointers a
20ea0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a re invalidated..
20eb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
20ec0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 and easiest to
20ed0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 remember policy
20ee0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
20ef0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
20f00 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
20f10 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
20f20 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
20f30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
20f40 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
20f50 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
20f60 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
20f70 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
20f80 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
20f90 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
20fa0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
20fb0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
20fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
20fd0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
20fe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
20ff0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
21000 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
21010 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
21020 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
21030 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
21040 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
21050 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
21060 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
21070 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
21080 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
21090 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
210a0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
210b0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
210c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
210d0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
210e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
210f0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
21100 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
21110 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
21120 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
21130 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
21140 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
21150 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
21160 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
21170 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
21180 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
21190 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
211a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
211b0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
211c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
211d0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
211e0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 * The pointers r
211f0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 eturned are vali
21200 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 d until a type c
21210 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
21220 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 as.** described
21230 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c above, or until
21240 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
21250 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
21260 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
21270 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
21280 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ] is called. Th
21290 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 e memory space u
212a0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 sed to hold stri
212b0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 ngs.** and BLOBs
212c0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 is freed automa
212d0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e tically. Do <b>
212e0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 not</b> pass the
212f0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
21300 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ed.** [sqlite3_c
21310 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b olumn_blob()], [
21320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
21330 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 ext()], etc. int
21340 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 o.** [sqlite3_fr
21350 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ee()]..**.** If
21360 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
21370 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ion error occurs
21380 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c during the eval
21390 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a uation of any.**
213a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
213b0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 es, a default va
213c0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
213d0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 The default va
213e0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 lue.** is either
213f0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 the integer 0,
21400 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 the floating poi
21410 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f nt number 0.0, o
21420 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e r a NULL.** poin
21430 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 ter. Subsequent
21440 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
21450 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 e3_errcode()] wi
21460 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 ll return.** [SQ
21470 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a LITE_NOMEM]..**.
21480 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
21490 0a 2a 2a 20 5b 48 31 33 38 30 33 5d 20 5b 48 31 .** [H13803] [H1
214a0 33 38 30 36 5d 20 5b 48 31 33 38 30 39 5d 20 5b 3806] [H13809] [
214b0 48 31 33 38 31 32 5d 20 5b 48 31 33 38 31 35 5d H13812] [H13815]
214c0 20 5b 48 31 33 38 31 38 5d 20 5b 48 31 33 38 32 [H13818] [H1382
214d0 31 5d 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 1] [H13824].** [
214e0 48 31 33 38 32 37 5d 20 5b 48 31 33 38 33 30 5d H13827] [H13830]
214f0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
21500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21510 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
21520 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
21530 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
21540 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 _bytes(sqlite3_s
21550 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
21560 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
21570 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
21580 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
21590 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c Col);.double sql
215a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
215b0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
215c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
215d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
215e0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
215f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
21600 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
21610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 te3_column_int64
21620 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
21630 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 int iCol);.const
21640 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
21650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
21660 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
21670 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
21680 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
21690 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
216a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
216b0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
216c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
216d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
216e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 int iCol);.sqli
216f0 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 te3_value *sqlit
21700 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
21710 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21720 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a nt iCol);../*.**
21730 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 CAPI3REF: Destr
21740 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 oy A Prepared St
21750 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b atement Object {
21760 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e H13300} <S70300>
21770 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30100>.**.** T
21780 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
21790 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
217a0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
217b0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
217c0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 tatement]..** If
217d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
217e0 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 as executed succ
217f0 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 essfully or not
21800 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c executed at all,
21810 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f then.** SQLITE_
21820 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 OK is returned.
21830 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 If execution of
21840 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 the statement fa
21850 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 iled then an.**
21860 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 [error code] or
21870 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
21880 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
21890 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f d..**.** This ro
218a0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c utine can be cal
218b0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 led at any point
218c0 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 during the exec
218d0 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 ution of the.**
218e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
218f0 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 ent]. If the vi
21900 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 rtual machine ha
21910 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 s not.** complet
21920 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 ed execution whe
21930 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 n this routine i
21940 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 s called, that i
21950 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e s like.** encoun
21960 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 tering an error
21970 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 or an [sqlite3_i
21980 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 nterrupt | inter
21990 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 rupt]..** Incomp
219a0 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 lete updates may
219b0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
219c0 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 and transactions
219d0 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 canceled,.** de
219e0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
219f0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e ircumstances, an
21a00 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 d the.** [error
21a10 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 code] returned w
21a20 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 ill be [SQLITE_A
21a30 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 BORT]..**.** Req
21a40 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
21a50 31 31 33 30 32 5d 20 5b 48 31 31 33 30 34 5d 0a 11302] [H11304].
21a60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 */.int sqlite3_f
21a70 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f inalize(sqlite3_
21a80 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
21a90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
21aa0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 eset A Prepared
21ab0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
21ac0 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 {H13330} <S7030
21ad0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
21ae0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e ite3_reset() fun
21af0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
21b00 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 to reset a [prep
21b10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
21b20 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 ** object back t
21b30 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
21b40 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 ate, ready to be
21b50 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a re-executed..**
21b60 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 Any SQL stateme
21b70 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
21b80 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
21b90 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
21ba0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
21bb0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
21bc0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
21bd0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
21be0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
21bf0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
21c00 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
21c10 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
21c20 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 .**.** {H11332}
21c30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
21c40 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 et(S)] interface
21c50 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 resets the [pre
21c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
21c70 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 S.** b
21c80 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e ack to the begin
21c90 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 ning of its prog
21ca0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 ram..**.** {H113
21cb0 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 34} If the most
21cc0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
21cd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
21ce0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
21cf0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
21d00 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 tatement] S retu
21d10 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
21d20 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
21d30 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 E],.**
21d40 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 or if [sqlite3_s
21d50 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 tep(S)] has neve
21d60 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 r before been ca
21d70 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 lled on S,.**
21d80 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c then [sql
21d90 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
21da0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
21db0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 K]..**.** {H1133
21dc0 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 6} If the most r
21dd0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
21de0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
21df0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 for the.**
21e00 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
21e10 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
21e20 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
21e30 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
21e40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
21e50 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 )] returns an ap
21e60 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 propriate [error
21e70 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 code]..**.** {H
21e80 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 11338} The [sqli
21e90 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
21ea0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
21eb0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
21ec0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f es.** o
21ed0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 f any [sqlite3_b
21ee0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 ind_blob|binding
21ef0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 s] on the [prepa
21f00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
21f10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
21f20 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 _reset(sqlite3_s
21f30 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
21f40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 .** CAPI3REF: Cr
21f50 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 eate Or Redefine
21f60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b SQL Functions {
21f70 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e H16100} <S20200>
21f80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 .** KEYWORDS: {f
21f90 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
21fa0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 routines}.** KE
21fb0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
21fc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
21fd0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 function}.** KE
21fe0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
21ff0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
22000 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a functions}.**.*
22010 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 * These two func
22020 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 tions (collectiv
22030 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 ely known as "fu
22040 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
22050 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 routines").** ar
22060 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 e used to add SQ
22070 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
22080 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 ggregates or to
22090 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 redefine the beh
220a0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 avior.** of exis
220b0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f ting SQL functio
220c0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
220d0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 . The only diff
220e0 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 erence between t
220f0 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 he.** two is tha
22100 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 t the second par
22110 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 ameter, the name
22120 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 of the (scalar)
22130 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
22140 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e aggregate, is en
22150 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 coded in UTF-8 f
22160 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
22170 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 e_function() and
22180 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 UTF-16.** for s
22190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
221a0 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a nction16()..**.*
221b0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
221c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
221d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
221e0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
221f0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
22200 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
22210 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f If a single pro
22220 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 gram uses more t
22230 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 han one database
22240 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 .** connection i
22250 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 nternally, then
22260 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 SQL functions mu
22270 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 st be added indi
22280 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 vidually to.** e
22290 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
222a0 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 nection..**.** T
222b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
222c0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
222d0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 of the SQL funct
222e0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 ion to be create
222f0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 d or.** redefine
22300 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f d. The length o
22310 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 f the name is li
22320 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 mited to 255 byt
22330 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 es, exclusive of
22340 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 .** the zero-ter
22350 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 minator. Note t
22360 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e hat the name len
22370 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 gth limit is in
22380 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 bytes, not.** ch
22390 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 aracters. Any a
223a0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 ttempt to create
223b0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 a function with
223c0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a a longer name.*
223d0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e * will result in
223e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
223f0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a being returned..
22400 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 **.** The third
22410 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
22420 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
22430 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
22440 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
22450 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
22460 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 gate takes. If t
22470 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 his parameter is
22480 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
22490 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
224a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
224b0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 may take any nu
224c0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
224d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 s..**.** The fou
224e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
224f0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
22500 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
22510 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
22520 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
22530 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
22540 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
22550 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 rameters. Any S
22560 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c QL function impl
22570 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
22580 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 d be able to wor
22590 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 k.** work with U
225a0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 TF-8, UTF-16le,
225b0 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 or UTF-16be. Bu
225c0 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 t some implement
225d0 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a ations may be.**
225e0 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 more efficient
225f0 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e with one encodin
22600 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 g than another.
22610 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 It is allowed t
22620 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
22630 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
22640 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ion() or sqlite3
22650 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
22660 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 16() multiple.**
22670 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 times with the
22680 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 same function bu
22690 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 t with different
226a0 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 values of eText
226b0 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c Rep..** When mul
226c0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
226d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
226e0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 e function are a
226f0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 vailable, SQLite
22700 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 .** will pick th
22710 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c e one that invol
22720 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d ves the least am
22730 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e ount of data con
22740 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 version..** If t
22750 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 here is only a s
22760 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ingle implementa
22770 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 tion which does
22780 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 not care what te
22790 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 xt.** encoding i
227a0 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 s used, then the
227b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
227c0 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 should be [SQLI
227d0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 TE_ANY]..**.** T
227e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
227f0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
22800 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 ry pointer. The
22810 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
22820 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 of the.** functi
22830 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 on can gain acce
22840 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 ss to this point
22850 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 er using [sqlite
22860 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 3_user_data()]..
22870 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 **.** The sevent
22880 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 h, eighth and ni
22890 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 nth parameters,
228a0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 xFunc, xStep and
228b0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 xFinal, are.**
228c0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 pointers to C-la
228d0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 nguage functions
228e0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
228f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
22900 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
22910 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 . A scalar SQL f
22920 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 unction requires
22930 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 an implementati
22940 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a on of the xFunc.
22950 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 ** callback only
22960 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 , NULL pointers
22970 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 should be passed
22980 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e as the xStep an
22990 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 d xFinal.** para
229a0 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 meters. An aggre
229b0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
229c0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
229d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
229e0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 xStep.** and xFi
229f0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f nal and NULL sho
22a00 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f uld be passed fo
22a10 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 r xFunc. To dele
22a20 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a te an existing.*
22a30 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f * SQL function o
22a40 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 r aggregate, pas
22a50 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 s NULL for all t
22a60 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 hree function ca
22a70 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 llbacks..**.** I
22a80 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 t is permitted t
22a90 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 o register multi
22aa0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
22ab0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a ons of the same.
22ac0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 ** functions wit
22ad0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 h the same name
22ae0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 but with either
22af0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 differing number
22b00 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 s of.** argument
22b10 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 s or differing p
22b20 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
22b30 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 codings. SQLite
22b40 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 will use.** the
22b50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
22b60 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 most closely mat
22b70 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 ches the way in
22b80 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c which the.** SQL
22b90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
22ba0 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 d. A function i
22bb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
22bc0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 th a non-negativ
22bd0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 e.** nArg parame
22be0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 ter is a better
22bf0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
22c00 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
22c10 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e tion with.** a n
22c20 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 egative nArg. A
22c30 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
22c40 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 the preferred te
22c50 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d xt encoding.** m
22c60 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 atches the datab
22c70 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ase encoding is
22c80 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 a better.** matc
22c90 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
22ca0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
22cb0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e ding is differen
22cc0 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 t. .** A functi
22cd0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
22ce0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
22cf0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 is between UTF1
22d00 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 6le and UTF16be.
22d10 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d ** is a closer m
22d20 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
22d30 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
22d40 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e ncoding differen
22d50 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e ce is.** between
22d60 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e UTF8 and UTF16.
22d70 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 .**.** Built-in
22d80 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
22d90 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
22da0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
22db0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
22dc0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
22dd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
22de0 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ed function with
22df0 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 a given name ov
22e00 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 errides all.** b
22e10 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e uilt-in function
22e20 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 s in the same [d
22e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
22e40 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d on] with the sam
22e50 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 e name..** Subse
22e60 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f quent applicatio
22e70 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
22e80 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
22e90 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 name only overri
22ea0 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 de .** prior app
22eb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
22ec0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
22ed0 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 are an exact mat
22ee0 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 ch for the.** nu
22ef0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 mber of paramete
22f00 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 rs and preferred
22f10 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
22f20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
22f30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
22f40 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
22f50 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 call other.** S
22f60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
22f70 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 . However, such
22f80 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a calls must not.
22f90 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ** close the dat
22fa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22fb0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 nor finalize or
22fc0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 reset the prepa
22fd0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
22fe0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 in which the fu
22ff0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
23000 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 g..**.** Require
23010 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 ments:.** [H1610
23020 33 5d 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 3] [H16106] [H16
23030 31 30 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 109] [H16112] [H
23040 31 36 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 16118] [H16121]
23050 5b 48 31 36 31 32 34 5d 20 5b 48 31 36 31 32 37 [H16124] [H16127
23060 5d 0a 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48 ].** [H16130] [H
23070 31 36 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20 16133] [H16136]
23080 5b 48 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32 [H16139] [H16142
23090 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
230a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
230b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
230c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
230d0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
230e0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
230f0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
23100 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
23110 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
23120 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
23130 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
23140 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
23150 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
23160 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
23170 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
23180 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
23190 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 ontext*).);.int
231a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
231b0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c unction16(. sql
231c0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
231d0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f t void *zFunctio
231e0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
231f0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
23200 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
23210 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
23220 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
23230 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
23240 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
23250 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
23260 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
23270 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
23280 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
23290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
232a0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
232b0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 3REF: Text Encod
232c0 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 ings {H10267} <S
232d0 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 50200> <H16100>.
232e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
232f0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 tant define inte
23300 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 ger codes that r
23310 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 epresent the var
23320 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 ious.** text enc
23330 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 odings supported
23340 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 by SQLite..*/.#
23350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
23360 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 F8 1.#
23370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
23380 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 F16LE 2.#
23390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
233a0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 F16BE 3.#
233b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
233c0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 F16 4
233d0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 /* Use native
233e0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 byte order */.#d
233f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 efine SQLITE_ANY
23400 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 5
23410 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
23420 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 te_function only
23430 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
23440 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
23450 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 8 /* sqlite
23460 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
23470 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a on only */../*.*
23480 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 * CAPI3REF: Depr
23490 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 ecated Functions
234a0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a .** DEPRECATED.*
234b0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
234c0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 ions are [deprec
234d0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 ated]. In order
234e0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 to maintain.**
234f0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
23500 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 ibility with old
23510 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 er code, these f
23520 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 unctions continu
23530 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 e .** to be supp
23540 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c orted. However,
23550 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
23560 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a s should avoid.*
23570 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 * the use of the
23580 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 se functions. T
23590 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 o help encourage
235a0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 people to avoid
235b0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 .** using these
235c0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 functions, we ar
235d0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 e not going to t
235e0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 ell you what the
235f0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 y do..*/.#ifndef
23600 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 SQLITE_OMIT_DEP
23610 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 RECATED.SQLITE_D
23620 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
23630 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
23640 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f count(sqlite3_co
23650 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
23660 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
23670 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 qlite3_expired(s
23680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 qlite3_stmt*);.S
23690 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
236a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 int sqlite3_tra
236b0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 nsfer_bindings(s
236c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 qlite3_stmt*, sq
236d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 lite3_stmt*);.SQ
236e0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
236f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 int sqlite3_glob
23700 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 al_recover(void)
23710 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 ;.SQLITE_DEPRECA
23720 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 TED void sqlite3
23730 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 _thread_cleanup(
23740 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 void);.SQLITE_DE
23750 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
23760 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 ite3_memory_alar
23770 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c m(void(*)(void*,
23780 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e sqlite3_int64,in
23790 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 t),void*,sqlite3
237a0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a _int64);.#endif.
237b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
237c0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 Obtaining SQL F
237d0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 unction Paramete
237e0 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 r Values {H15100
237f0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
23800 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 The C-language
23810 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
23820 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 f SQL functions
23830 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 and aggregates u
23840 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 ses.** this set
23850 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 of interface rou
23860 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 tines to access
23870 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 the parameter va
23880 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 lues on.** the f
23890 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
238a0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gate..**.** The
238b0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 xFunc (for scala
238c0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 r functions) or
238d0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 xStep (for aggre
238e0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 gates) parameter
238f0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 s.** to [sqlite3
23900 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
23910 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
23920 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
23930 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 16()].** define
23940 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 callbacks that i
23950 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
23960 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
23970 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 ggregates..** Th
23980 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
23990 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 to these callbac
239a0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ks is an array o
239b0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a f pointers to.**
239c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
239d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
239e0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e ts. There is on
239f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
23a00 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 ] object for.**
23a10 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 each parameter t
23a20 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 o the SQL functi
23a30 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 on. These routi
23a40 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a nes are used to.
23a50 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 ** extract value
23a60 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 s from the [sqli
23a70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
23a80 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ts..**.** These
23a90 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e routines work on
23aa0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 ly with [protect
23ab0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
23ac0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e ] objects..** An
23ad0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 y attempt to use
23ae0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
23af0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 on an [unprotect
23b00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
23b10 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 ].** object resu
23b20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
23b30 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
23b40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
23b50 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 work just like t
23b60 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
23b70 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
23b80 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 functions].** ex
23b90 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 cept that these
23ba0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 routines take a
23bb0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 single [protect
23bc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
23bd0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e ] object.** poin
23be0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 ter instead of a
23bf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
23c00 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 pointer and an
23c10 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e integer column n
23c20 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 umber..**.** The
23c30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
23c40 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 ext16() interfac
23c50 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 e extracts a UTF
23c60 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e -16 string.** in
23c70 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
23c80 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f -order of the ho
23c90 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 st machine. The
23ca0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
23cb0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
23cc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
23cd0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
23ce0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
23cf0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
23d00 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
23d10 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
23d20 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
23d30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
23d40 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
23d50 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 e() interface at
23d60 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a tempts to apply.
23d70 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e ** numeric affin
23d80 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 ity to the value
23d90 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 . This means th
23da0 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 at an attempt is
23db0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 .** made to conv
23dc0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f ert the value to
23dd0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 an integer or f
23de0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 loating point.
23df0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e If.** such a con
23e00 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 version is possi
23e10 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 ble without loss
23e20 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 of information
23e30 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 (in other.** wor
23e40 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 ds, if the value
23e50 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 is a string tha
23e60 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e t looks like a n
23e70 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 umber).** then t
23e80 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 he conversion is
23e90 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 performed. Oth
23ea0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 erwise no conver
23eb0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 sion occurs..**
23ec0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 The [SQLITE_INTE
23ed0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 GER | datatype]
23ee0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e after conversion
23ef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
23f00 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 .** Please pay p
23f10 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 articular attent
23f20 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 ion to the fact
23f30 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 that the pointer
23f40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
23f50 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
23f60 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
23f70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
23f80 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
23f90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
23fa0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
23fb0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
23fc0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
23fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
23fe0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
23ff0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
24000 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
24010 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
24020 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
24030 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a text16()]..**.**
24040 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
24050 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
24060 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
24070 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 ead as.** the SQ
24080 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 L function that
24090 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 supplied the [sq
240a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 lite3_value*] pa
240b0 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 rameters..**.**
240c0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
240d0 20 5b 48 31 35 31 30 33 5d 20 5b 48 31 35 31 30 [H15103] [H1510
240e0 36 5d 20 5b 48 31 35 31 30 39 5d 20 5b 48 31 35 6] [H15109] [H15
240f0 31 31 32 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48 112] [H15115] [H
24100 31 35 31 31 38 5d 20 5b 48 31 35 31 32 31 5d 20 15118] [H15121]
24110 5b 48 31 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 [H15124].** [H15
24120 31 32 37 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48 127] [H15130] [H
24130 31 35 31 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a 15133] [H15136].
24140 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 */.const void *s
24150 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
24160 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a b(sqlite3_value*
24170 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
24180 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 alue_bytes(sqlit
24190 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
241a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
241b0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 tes16(sqlite3_va
241c0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 lue*);.double sq
241d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 lite3_value_doub
241e0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
241f0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
24200 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 value_int(sqlite
24210 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 3_value*);.sqlit
24220 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
24230 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c _value_int64(sql
24240 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f ite3_value*);.co
24250 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
24260 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r *sqlite3_value
24270 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 _text(sqlite3_va
24280 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
24290 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
242a0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
242b0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 value*);.const v
242c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
242d0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 ue_text16le(sqli
242e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
242f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
24300 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
24310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
24320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
24330 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ue_type(sqlite3_
24340 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
24350 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
24360 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ic_type(sqlite3_
24370 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 value*);../*.**
24380 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
24390 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 Aggregate Funct
243a0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 ion Context {H16
243b0 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 210} <S20200>.**
243c0 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e .** The implemen
243d0 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 tation of aggreg
243e0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
243f0 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 s use this routi
24400 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a ne to allocate.*
24410 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f * a structure fo
24420 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 r storing their
24430 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 state..**.** The
24440 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 first time the
24450 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
24460 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 e_context() rout
24470 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f ine is called fo
24480 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 r a.** particula
24490 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c r aggregate, SQL
244a0 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 ite allocates nB
244b0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 ytes of memory,
244c0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a zeroes out that.
244d0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 ** memory, and r
244e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
244f0 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e to it. On secon
24500 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
24510 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c calls to.** sql
24520 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
24530 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 ontext() for the
24540 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
24550 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a function index,.
24560 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 ** the same buff
24570 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
24580 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
24590 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 on of the aggreg
245a0 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 ate can use.** t
245b0 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 he returned buff
245c0 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 er to accumulate
245d0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c data..**.** SQL
245e0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ite automaticall
245f0 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f y frees the allo
24600 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 cated buffer whe
24610 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a n the aggregate.
24620 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 ** query conclud
24630 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 es..**.** The fi
24640 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 rst parameter sh
24650 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f ould be a copy o
24660 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
24670 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 3_context | SQL
24680 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 function context
24690 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 ] that is the fi
246a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a rst parameter.**
246b0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
246c0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d routine that im
246d0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 plements the agg
246e0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e regate function.
246f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
24700 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c ine must be call
24710 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
24720 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
24730 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 .** the aggregat
24740 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 e SQL function i
24750 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
24760 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
24770 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 32 * [H16211] [H162
24780 31 33 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 31 13] [H16215] [H1
24790 36 32 31 37 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 6217].*/.void *s
247a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
247b0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 _context(sqlite3
247c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
247d0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 Bytes);../*.** C
247e0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 API3REF: User Da
247f0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 ta For Functions
24800 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30 {H16240} <S2020
24810 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
24820 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
24830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
24840 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
24850 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 the pointer that
24860 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 was the pUserDa
24870 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 ta parameter (th
24880 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 e 5th parameter)
24890 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
248a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
248b0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
248c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
248d0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
248e0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
248f0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
24900 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
24910 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
24920 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ion. {END}.**.**
24930 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 This routine mu
24940 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
24950 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
24960 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
24970 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
24980 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
24990 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
249a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
249b0 2a 20 5b 48 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f * [H16243].*/.vo
249c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 id *sqlite3_user
249d0 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f _data(sqlite3_co
249e0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
249f0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
24a00 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f se Connection Fo
24a10 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 r Functions {H16
24a20 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 250} <S60600><S2
24a30 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0200>.**.** The
24a40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
24a50 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 db_handle() inte
24a60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
24a70 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 copy of.** the p
24a80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 ointer to the [d
24a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24aa0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 on] (the 1st par
24ab0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 ameter).** of th
24ac0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
24ad0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a e_function()].**
24ae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
24af0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
24b00 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 )] routines that
24b10 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 originally.** r
24b20 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 egistered the ap
24b30 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
24b40 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a d function..**.*
24b50 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
24b60 2a 2a 20 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 ** [H16253].*/.s
24b70 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f qlite3 *sqlite3_
24b80 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
24b90 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
24ba0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
24bb0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 3REF: Function A
24bc0 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 uxiliary Data {H
24bd0 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 16270} <S20200>.
24be0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 **.** The follow
24bf0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ing two function
24c00 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
24c10 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
24c20 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f tions to.** asso
24c30 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 ciate metadata w
24c40 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c ith argument val
24c50 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 ues. If the same
24c60 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 value is passed
24c70 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 to.** multiple
24c80 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
24c90 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 he same SQL func
24ca0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 tion during quer
24cb0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 y execution, und
24cc0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 er.** some circu
24cd0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 mstances the ass
24ce0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 ociated metadata
24cf0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 may be preserve
24d00 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 d. This may.** b
24d10 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d e used, for exam
24d20 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 ple, to add a re
24d30 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e gular-expression
24d40 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 matching scalar
24d50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 .** function. Th
24d60 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 e compiled versi
24d70 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 on of the regula
24d80 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 r expression is
24d90 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
24da0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
24db0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 with the SQL va
24dc0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
24dd0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
24de0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e sion.** pattern.
24df0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 The compiled r
24e00 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
24e10 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 n can be reused
24e20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 on multiple.** i
24e30 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
24e40 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
24e50 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 so that the orig
24e60 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 inal pattern str
24e70 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ing.** does not
24e80 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d need to be recom
24e90 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e piled on each in
24ea0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 vocation..**.**
24eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
24ec0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
24ed0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
24ee0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 inter to the met
24ef0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 adata.** associa
24f00 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
24f10 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
24f20 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 function with t
24f30 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a he Nth argument.
24f40 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 ** value to the
24f50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
24f60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 ned function. If
24f70 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 no metadata has
24f80 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 been ever.** be
24f90 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e en set for the N
24fa0 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 th argument of t
24fb0 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 he function, or
24fc0 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e if the correspon
24fd0 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ding.** function
24fe0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 parameter has c
24ff0 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 hanged since the
25000 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 meta-data was s
25010 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 et,.** then sqli
25020 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
25030 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c ) returns a NULL
25040 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
25050 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f The sqlite3_set_
25060 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
25070 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 ace saves the me
25080 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 tadata.** pointe
25090 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 d to by its 3rd
250a0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 parameter as the
250b0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 metadata for th
250c0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 e N-th.** argume
250d0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 nt of the applic
250e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
250f0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 nction. Subsequ
25100 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ent.** calls to
25110 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
25120 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 ata() might retu
25130 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 rn this data, if
25140 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 it has.** not b
25150 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a een destroyed..*
25160 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e * If it is not N
25170 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c ULL, SQLite will
25180 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 invoke the dest
25190 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 ructor.** functi
251a0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 on given by the
251b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
251c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
251d0 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 data() on.** the
251e0 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 metadata when t
251f0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
25200 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 function parame
25210 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f ter changes.** o
25220 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 r when the SQL s
25230 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 tatement complet
25240 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f es, whichever co
25250 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a mes first..**.**
25260 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 SQLite is free
25270 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 to call the dest
25280 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 ructor and drop
25290 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a metadata on any.
252a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 ** parameter of
252b0 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 any function at
252c0 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f any time. The o
252d0 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 nly guarantee is
252e0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 that.** the des
252f0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 tructor will be
25300 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 called before th
25310 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 e metadata is dr
25320 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 opped..**.** In
25330 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 practice, metada
25340 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 ta is preserved
25350 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e between function
25360 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 calls for.** ex
25370 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 pressions that a
25380 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 re constant at c
25390 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 ompile time. Thi
253a0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 s includes liter
253b0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 al.** values and
253c0 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a SQL variables..
253d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
253e0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
253f0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
25400 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
25410 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e h.** the SQL fun
25420 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
25430 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
25440 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 ents:.** [H16272
25450 5d 20 5b 48 31 36 32 37 34 5d 20 5b 48 31 36 32 ] [H16274] [H162
25460 37 36 5d 20 5b 48 31 36 32 37 37 5d 20 5b 48 31 76] [H16277] [H1
25470 36 32 37 38 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 6278] [H16279].*
25480 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
25490 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 get_auxdata(sqli
254a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
254b0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 t N);.void sqlit
254c0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 e3_set_auxdata(s
254d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
254e0 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 int N, void*, v
254f0 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b oid (*)(void*));
25500 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
25510 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 F: Constants Def
25520 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 ining Special De
25530 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f structor Behavio
25540 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 r {H10280} <S301
25550 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
25560 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 are special valu
25570 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 es for the destr
25580 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 uctor that is pa
25590 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a ssed in as the.*
255a0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 * final argument
255b0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b to routines lik
255c0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
255d0 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 t_blob()]. If t
255e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
255f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c argument is SQL
25600 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d ITE_STATIC, it m
25610 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
25620 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 ntent pointer is
25630 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 constant.** and
25640 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e will never chan
25650 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 ge. It does not
25660 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 need to be dest
25670 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 royed. The.** S
25680 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 QLITE_TRANSIENT
25690 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 value means that
256a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c the content wil
256b0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 l likely change
256c0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 in.** the near f
256d0 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 uture and that S
256e0 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b QLite should mak
256f0 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 e its own privat
25700 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 e copy of.** the
25710 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 content before
25720 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a returning..**.**
25730 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 The typedef is
25740 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 necessary to wor
25750 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d k around problem
25760 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 s in certain.**
25770 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 C++ compilers.
25780 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 See ticket #2191
25790 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 ..*/.typedef voi
257a0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 d (*sqlite3_dest
257b0 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 ructor_type)(voi
257c0 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c d*);.#define SQL
257d0 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 ITE_STATIC
257e0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 ((sqlite3_destru
257f0 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 ctor_type)0).#de
25800 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
25810 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 SIENT ((sqlite
25820 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
25830 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e)-1)../*.** CAP
25840 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 I3REF: Setting T
25850 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 he Result Of An
25860 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 SQL Function {H1
25870 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6400} <S20200>.*
25880 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
25890 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 nes are used by
258a0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 the xFunc or xFi
258b0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 nal callbacks th
258c0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 at.** implement
258d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
258e0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 d aggregates. S
258f0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ee.** [sqlite3_c
25900 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
25910 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
25920 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
25930 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 ()].** for addit
25940 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
25950 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 n..**.** These f
25960 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 unctions work ve
25970 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 ry much like the
25980 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 [parameter bind
25990 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a ing] family of.*
259a0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 * functions used
259b0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 to bind values
259c0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 to host paramete
259d0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 rs in prepared s
259e0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 tatements..** Re
259f0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 fer to the [SQL
25a00 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d parameter] docum
25a10 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 entation for add
25a20 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
25a30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
25a40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
25a50 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ob() interface s
25a60 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 ets the result f
25a70 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 rom.** an applic
25a80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
25a90 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
25aa0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 BLOB whose cont
25ab0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a ent is pointed.*
25ac0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f * to by the seco
25ad0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 nd parameter and
25ae0 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 which is N byte
25af0 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 s long where N i
25b00 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 s the.** third p
25b10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
25b20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
25b30 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e lt_zeroblob() in
25b40 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 terfaces set the
25b50 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 result of.** th
25b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
25b70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
25b80 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 o be a BLOB cont
25b90 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a aining all zero.
25ba0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 ** bytes and N b
25bb0 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 ytes in size, wh
25bc0 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c ere N is the val
25bd0 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 ue of the 2nd pa
25be0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 rameter..**.** T
25bf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
25c00 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 t_double() inter
25c10 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
25c20 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 sult from.** an
25c30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
25c40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
25c50 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f be a floating po
25c60 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 int value specif
25c70 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e ied.** by its 2n
25c80 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
25c90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
25ca0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
25cb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
25cc0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 error16() functi
25cd0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 ons.** cause the
25ce0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c implemented SQL
25cf0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 function to thr
25d00 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e ow an exception.
25d10 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
25d20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 the string point
25d30 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 ed to by the.**
25d40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
25d50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
25d60 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 error() or sqlit
25d70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
25d80 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 6().** as the te
25d90 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d xt of an error m
25da0 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 essage. SQLite
25db0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 interprets the e
25dc0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
25dd0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
25de0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
25df0 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c () as UTF-8. SQL
25e00 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ite.** interpret
25e10 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f s the string fro
25e20 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
25e30 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 _error16() as UT
25e40 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a F-16 in native.*
25e50 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 * byte order. I
25e60 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
25e70 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
25e80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
25e90 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
25ea0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
25eb0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 s negative then
25ec0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 SQLite takes as
25ed0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
25ee0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 sage all text up
25ef0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
25f00 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
25f10 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 r..** If the thi
25f20 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
25f30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
25f40 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c rror() or.** sql
25f50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
25f60 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 r16() is non-neg
25f70 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 ative then SQLit
25f80 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e e takes that man
25f90 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 y.** bytes (not
25fa0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d characters) from
25fb0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
25fc0 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 er as the error
25fd0 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 message..** The
25fe0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
25ff0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 rror() and sqlit
26000 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
26010 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6().** routines
26020 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 make a private c
26030 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 opy of the error
26040 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 message text be
26050 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 fore.** they ret
26060 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 urn. Hence, the
26070 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
26080 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 n can deallocate
26090 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 or.** modify th
260a0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 e text after the
260b0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 y return without
260c0 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 harm..** The sq
260d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
260e0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 or_code() functi
260f0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 on changes the e
26100 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 rror code.** ret
26110 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 urned by SQLite
26120 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 as a result of a
26130 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e n error in a fun
26140 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 ction. By defau
26150 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 lt,.** the error
26160 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f code is SQLITE_
26170 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 ERROR. A subseq
26180 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
26190 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
261a0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 r().** or sqlite
261b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
261c0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 () resets the er
261d0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 ror code to SQLI
261e0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 TE_ERROR..**.**
261f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
26200 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 lt_toobig() inte
26210 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
26220 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ite to throw an
26230 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 error.** indicat
26240 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e ing that a strin
26250 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 g or BLOB is to
26260 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e long to represen
26270 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c t..**.** The sql
26280 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 ite3_result_nome
26290 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 m() interface ca
262a0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
262b0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a hrow an error.**
262c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
262d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
262e0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a tion failed..**.
262f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
26300 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 esult_int() inte
26310 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
26320 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
26330 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
26340 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
26350 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d on to be the 32-
26360 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
26370 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
26380 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
26390 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 ument..** The sq
263a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
263b0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 64() interface s
263c0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
263d0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
263e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
263f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
26400 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 e the 64-bit sig
26410 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 ned integer.** v
26420 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 alue given in th
26430 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a e 2nd argument..
26440 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
26450 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 3_result_null()
26460 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
26470 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
26480 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
26490 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
264a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c nction to be NUL
264b0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c L..**.** The sql
264c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
264d0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 (), sqlite3_resu
264e0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 lt_text16(),.**
264f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
26500 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 ext16le(), and s
26510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
26520 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 xt16be() interfa
26530 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 ces.** set the r
26540 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
26550 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
26560 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
26570 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 to be.** a text
26580 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 string which is
26590 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 represented as U
265a0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 TF-8, UTF-16 nat
265b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a ive byte order,.
265c0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 ** UTF-16 little
265d0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d endian, or UTF-
265e0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 16 big endian, r
265f0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
26600 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 SQLite takes the
26610 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f text result fro
26620 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f m the applicatio
26630 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e n from.** the 2n
26640 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 d parameter of t
26650 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
26660 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
26670 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 es..** If the 3r
26680 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
26690 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
266a0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
266b0 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 es.** is negativ
266c0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 e, then SQLite t
266d0 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 akes result text
266e0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 from the 2nd pa
266f0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 rameter.** throu
26700 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
26710 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
26720 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
26730 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
26740 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
26750 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
26760 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
26770 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 then as many byt
26780 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
26790 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a rs) of the text.
267a0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
267b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
267c0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 er are taken as
267d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
267e0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 defined.** funct
267f0 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 ion result..** I
26800 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
26810 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
26820 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
26830 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
26840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
26850 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 blob is a non-NU
26860 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
26870 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 SQLite calls th
26880 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 at.** function a
26890 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 s the destructor
268a0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 on the text or
268b0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e BLOB result when
268c0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 it has.** finis
268d0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
268e0 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 esult..** If the
268f0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
26900 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
26910 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
26920 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 faces or.** sqli
26930 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
26940 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
26950 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
26960 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
26970 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
26980 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
26990 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
269a0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
269b0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
269c0 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 copy the it or c
269d0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 all a destructor
269e0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
269f0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
26a00 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 result..** If t
26a10 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
26a20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
26a30 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
26a40 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 erfaces.** or sq
26a50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
26a60 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c b is the special
26a70 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 constant SQLITE
26a80 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 _TRANSIENT.** th
26a90 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 en SQLite makes
26aa0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 a copy of the re
26ab0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 sult into space
26ac0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a obtained from.**
26ad0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
26ae0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 alloc()] before
26af0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a it returns..**.*
26b00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
26b10 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 sult_value() int
26b20 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
26b30 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 result of.** the
26b40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
26b50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
26b60 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a be a copy the.*
26b70 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
26b80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
26b90 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 ject specified b
26ba0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 y the 2nd parame
26bb0 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c ter. The.** sql
26bc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
26bd0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 e() interface ma
26be0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
26bf0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
26c00 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 ].** so that the
26c10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
26c20 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 specified in th
26c30 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
26c40 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 change or.** be
26c50 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 deallocated afte
26c60 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
26c70 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 _value() returns
26c80 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a without harm..*
26c90 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 * A [protected s
26ca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
26cb0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 ject may always
26cc0 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e be used where an
26cd0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
26ce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
26cf0 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 object is requir
26d00 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a ed, so either.**
26d10 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 kind of [sqlite
26d20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
26d30 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 can be used with
26d40 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
26d50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 .**.** If these
26d60 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
26d70 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 led from within
26d80 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 the different th
26d90 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 read.** than the
26da0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 one containing
26db0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
26dc0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
26dd0 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a that received.*
26de0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * the [sqlite3_c
26df0 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c ontext] pointer,
26e00 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
26e10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
26e20 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
26e30 2a 2a 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36 ** [H16403] [H16
26e40 34 30 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48 406] [H16409] [H
26e50 31 36 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20 16412] [H16415]
26e60 5b 48 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31 [H16418] [H16421
26e70 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 ] [H16424].** [H
26e80 31 36 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20 16427] [H16430]
26e90 5b 48 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36 [H16433] [H16436
26ea0 5d 20 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34 ] [H16439] [H164
26eb0 34 32 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31 42] [H16445] [H1
26ec0 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 6448].** [H16451
26ed0 5d 20 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34 ] [H16454] [H164
26ee0 35 37 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31 57] [H16460] [H1
26ef0 36 34 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6463].*/.void sq
26f00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
26f10 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 b(sqlite3_contex
26f20 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
26f30 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
26f40 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
26f50 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c te3_result_doubl
26f60 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
26f70 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 t*, double);.voi
26f80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
26f90 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 _error(sqlite3_c
26fa0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 ontext*, const c
26fb0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 har*, int);.void
26fc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
26fd0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f error16(sqlite3_
26fe0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
26ff0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 void*, int);.voi
27000 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27010 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 _error_toobig(sq
27020 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
27030 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
27040 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d sult_error_nomem
27050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
27060 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
27070 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
27080 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 de(sqlite3_conte
27090 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 xt*, int);.void
270a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
270b0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
270c0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 xt*, int);.void
270d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
270e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e nt64(sqlite3_con
270f0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 text*, sqlite3_i
27100 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 nt64);.void sqli
27110 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 te3_result_null(
27120 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
27130 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
27140 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 result_text(sqli
27150 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
27160 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 nst char*, int,
27170 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
27180 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
27190 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 sult_text16(sqli
271a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
271b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
271c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
271d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
271e0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 sult_text16le(sq
271f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
27200 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
27210 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
27220 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
27230 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 esult_text16be(s
27240 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
27250 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
27260 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
27270 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
27280 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c result_value(sql
27290 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 ite3_context*, s
272a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
272b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
272c0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c ult_zeroblob(sql
272d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
272e0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt n);../*.** CA
272f0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e PI3REF: Define N
27300 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 ew Collating Seq
27310 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 uences {H16600}
27320 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20300>.**.** T
27330 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
27340 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e re used to add n
27350 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ew collation seq
27360 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a uences to the.**
27370 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
27380 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 ction] specified
27390 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
273a0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
273b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 e name of the ne
273c0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 w collation sequ
273d0 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65 ence is specifie
273e0 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 d as a UTF-8 str
273f0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 ing.** for sqlit
27400 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
27410 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ion() and sqlite
27420 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
27430 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 on_v2().** and a
27440 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 UTF-16 string f
27450 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
27460 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e e_collation16().
27470 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a In all cases.**
27480 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 the name is pas
27490 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
274a0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
274b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ent..**.** The t
274c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 hird argument ma
274d0 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 y be one of the
274e0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 constants [SQLIT
274f0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c E_UTF8],.** [SQL
27500 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 ITE_UTF16LE] or
27510 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
27520 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 , indicating tha
27530 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c t the user-suppl
27540 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 ied.** routine e
27550 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 xpects to be pas
27560 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 sed pointers to
27570 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 strings encoded
27580 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 using UTF-8,.**
27590 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e UTF-16 little-en
275a0 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 dian, or UTF-16
275b0 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 big-endian, resp
275c0 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a ectively. The.**
275d0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
275e0 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 might also be [S
275f0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
27600 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 NED] to indicate
27610 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 that.** the rou
27620 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 tine expects poi
27630 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 nters to 16-bit
27640 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 word aligned str
27650 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 ings.** of UTF-1
27660 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
27670 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 byte order of th
27680 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e e host computer.
27690 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 .**.** A pointer
276a0 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 to the user sup
276b0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 plied routine mu
276c0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 st be passed as
276d0 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 the fifth.** arg
276e0 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 ument. If it is
276f0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 NULL, this is t
27700 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 he same as delet
27710 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f ing the collatio
27720 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 n.** sequence (s
27730 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 o that SQLite ca
27740 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 nnot call it any
27750 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 more)..** Each t
27760 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 ime the applicat
27770 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e ion supplied fun
27780 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 ction is invoked
27790 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a , it is passed.*
277a0 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 * as its first p
277b0 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 arameter a copy
277c0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 of the void* pas
277d0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 sed as the fourt
277e0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f h argument.** to
277f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
27800 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 collation() or s
27810 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
27820 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a llation16()..**.
27830 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 ** The remaining
27840 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
27850 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 e application-su
27860 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 pplied routine a
27870 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a re two strings,.
27880 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e ** each represen
27890 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 ted by a (length
278a0 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 , data) pair and
278b0 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 encoded in the
278c0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 encoding.** that
278d0 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 was passed as t
278e0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
278f0 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 t when the colla
27900 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 tion sequence wa
27910 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e s.** registered.
27920 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c {END} The appl
27930 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
27940 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e collation routin
27950 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 e should.** retu
27960 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 rn negative, zer
27970 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 o or positive if
27980 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e the first strin
27990 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a g is less than,.
279a0 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 ** equal to, or
279b0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 greater than the
279c0 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 second string.
279d0 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 i.e. (STRING1 -
279e0 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 STRING2)..**.**
279f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 The sqlite3_crea
27a00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
27a10 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c ) works like sql
27a20 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
27a30 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 ation().** excep
27a40 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 t that it takes
27a50 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e an extra argumen
27a60 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73 t which is a des
27a70 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 tructor for.** t
27a80 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 he collation. T
27a90 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
27aa0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 called when the
27ab0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a collation is.**
27ac0 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 destroyed and i
27ad0 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 s passed a copy
27ae0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 of the fourth pa
27af0 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f rameter void* po
27b00 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 inter.** of the
27b10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
27b20 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a ollation_v2()..*
27b30 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 * Collations are
27b40 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 destroyed when
27b50 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 they are overrid
27b60 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c den by later cal
27b70 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c ls to the.** col
27b80 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 lation creation
27b90 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 functions or whe
27ba0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
27bb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 connection] is c
27bc0 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b losed.** using [
27bd0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
27be0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
27bf0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 ents:.** [H16603
27c00 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 31 36 36 ] [H16604] [H166
27c10 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 5b 48 31 06] [H16609] [H1
27c20 36 36 31 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b 6612] [H16615] [
27c30 48 31 36 36 31 38 5d 20 5b 48 31 36 36 32 31 5d H16618] [H16621]
27c40 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 5b 48 31 .** [H16624] [H1
27c50 36 36 32 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 6627] [H16630].*
27c60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 /.int sqlite3_cr
27c70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a eate_collation(.
27c80 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 sqlite3*, . c
27c90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
27ca0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 , . int eTextRe
27cb0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 p, . void*,. i
27cc0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
27cd0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
27ce0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
27cf0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 id*).);.int sqli
27d00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
27d10 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 tion_v2(. sqlit
27d20 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 e3*, . const ch
27d30 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e ar *zName, . in
27d40 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
27d50 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f oid*,. int(*xCo
27d60 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
27d70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
27d80 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 ,const void*),.
27d90 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
27da0 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 (void*).);.int s
27db0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
27dc0 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c llation16(. sql
27dd0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 ite3*, . const
27de0 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 void *zName,. i
27df0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
27e00 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 void*,. int(*xC
27e10 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
27e20 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
27e30 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
27e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
27e50 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 F: Collation Nee
27e60 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 ded Callbacks {H
27e70 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 16700} <S20300>.
27e80 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 **.** To avoid h
27e90 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 aving to registe
27ea0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 r all collation
27eb0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 sequences before
27ec0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 a database.** c
27ed0 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 an be used, a si
27ee0 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ngle callback fu
27ef0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 nction may be re
27f00 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 gistered with th
27f10 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
27f20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 onnection] to be
27f30 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 called whenever
27f40 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f an undefined co
27f50 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
27f60 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e nce is required.
27f70 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 .**.** If the fu
27f80 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 nction is regist
27f90 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 ered using the s
27fa0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
27fb0 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a _needed() API,.*
27fc0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 * then it is pas
27fd0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 sed the names of
27fe0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
27ff0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 tion sequences a
28000 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 s strings.** enc
28010 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b oded in UTF-8. {
28020 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 H16703} If sqlit
28030 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
28040 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c ded16() is used,
28050 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 .** the names ar
28060 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d e passed as UTF-
28070 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 16 in machine na
28080 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
28090 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 .** A call to ei
280a0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 ther function re
280b0 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 places any exist
280c0 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ing callback..**
280d0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c .** When the cal
280e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
280f0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 , the first argu
28100 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 ment passed is a
28110 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 copy.** of the
28120 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
28130 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 to sqlite3_colla
28140 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 tion_needed() or
28150 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c .** sqlite3_coll
28160 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
28170 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
28180 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 gument is the da
28190 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
281a0 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 tion. The third
281b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 argument is one
281c0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 of [SQLITE_UTF8
281d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
281e0 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 BE],.** or [SQLI
281f0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 TE_UTF16LE], ind
28200 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 icating the most
28210 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 desirable form
28220 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e of the collation
28230 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e .** sequence fun
28240 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 ction required.
28250 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
28260 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
28270 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 e of the.** requ
28280 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ired collation s
28290 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 equence..**.** T
282a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
282b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 tion should regi
282c0 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 ster the desired
282d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 collation using
282e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
282f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d ate_collation()]
28300 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
28310 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d e_collation16()]
28320 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
28330 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
28340 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 n_v2()]..**.** R
28350 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
28360 5b 48 31 36 37 30 32 5d 20 5b 48 31 36 37 30 34 [H16702] [H16704
28370 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e ] [H16706].*/.in
28380 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 t sqlite3_collat
28390 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 ion_needed(. sq
283a0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a lite3*, . void*
283b0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 , . void(*)(voi
283c0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
283d0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 eTextRep,const c
283e0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c har*).);.int sql
283f0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
28400 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 eeded16(. sqlit
28410 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 e3*, . void*,.
28420 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
28430 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
28440 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a tRep,const void*
28450 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 ).);../*.** Spec
28460 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 ify the key for
28470 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 an encrypted dat
28480 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 abase. This rou
28490 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a tine should be.*
284a0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 * called right a
284b0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 fter sqlite3_ope
284c0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 n()..**.** The c
284d0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
284e0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
284f0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
28500 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
28510 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
28520 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 /.int sqlite3_ke
28530 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 y(. sqlite3 *db
28540 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
28550 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
28560 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
28570 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 . const void *p
28580 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 Key, int nKey
28590 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a /* The key */.
285a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 );../*.** Change
285b0 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f the key on an o
285c0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 pen database. I
285d0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 f the current da
285e0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a tabase is not.**
285f0 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 encrypted, this
28600 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e routine will en
28610 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e crypt it. If pN
28620 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 ew==0 or nNew==0
28630 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 , the.** databas
28640 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a e is decrypted..
28650 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
28660 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
28670 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
28680 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
28690 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
286a0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 f SQLite..*/.int
286b0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a sqlite3_rekey(.
286c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
286d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
286e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
286f0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
28700 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
28710 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
28720 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f * The new key */
28730 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
28740 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 REF: Suspend Exe
28750 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
28760 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d rt Time {H10530}
28770 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 <S40410>.**.**
28780 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 The sqlite3_slee
28790 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 p() function cau
287a0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 ses the current
287b0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e thread to suspen
287c0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 d execution.** f
287d0 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 or at least a nu
287e0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
287f0 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 onds specified i
28800 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e n its parameter.
28810 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 .**.** If the op
28820 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 erating system d
28830 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 oes not support
28840 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 sleep requests w
28850 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f ith.** milliseco
28860 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 nd time resoluti
28870 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d on, then the tim
28880 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 e will be rounde
28890 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e d up to.** the n
288a0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 earest second. T
288b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
288c0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
288d0 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 ep actually.** r
288e0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 equested from th
288f0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
28900 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a em is returned..
28910 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 **.** SQLite imp
28920 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 lements this int
28930 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e erface by callin
28940 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a g the xSleep().*
28950 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 * method of the
28960 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
28970 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
28980 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
28990 3a 20 5b 48 31 30 35 33 33 5d 20 5b 48 31 30 35 : [H10533] [H105
289a0 33 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 36].*/.int sqlit
289b0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a e3_sleep(int);..
289c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
289d0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 Name Of The Fold
289e0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f er Holding Tempo
289f0 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33 rary Files {H103
28a00 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 10} <S20000>.**.
28a10 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 ** If this globa
28a20 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
28a30 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
28a40 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
28a50 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
28a60 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e a folder (a.k.a.
28a70 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 directory), the
28a80 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 n all temporary
28a90 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 files.** created
28aa0 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 by SQLite will
28ab0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 be placed in tha
28ac0 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 t directory. If
28ad0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
28ae0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
28af0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
28b00 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 performs a sear
28b10 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 ch for an approp
28b20 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 riate.** tempora
28b30 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 ry file director
28b40 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e y..**.** It is n
28b50 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 ot safe to read
28b60 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 or modify this v
28b70 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 ariable in more
28b80 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 than one.** thre
28b90 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 ad at a time. I
28ba0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f t is not safe to
28bb0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 read or modify
28bc0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
28bd0 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 if a [database
28be0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 connection] is b
28bf0 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 eing used at the
28c00 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 same time in a
28c10 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 separate.** thre
28c20 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 ad..** It is int
28c30 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 ended that this
28c40 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 variable be set
28c50 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 once.** as part
28c60 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 of process initi
28c70 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 alization and be
28c80 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 fore any SQLite
28c90 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 interface.** rou
28ca0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 tines have been
28cb0 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 called and that
28cc0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 this variable re
28cd0 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a main unchanged.*
28ce0 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a * thereafter..**
28cf0 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70 5f 73 74 .** The [temp_st
28d00 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
28d10 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 agma] may modify
28d20 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 this variable a
28d30 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 nd cause.** it t
28d40 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
28d50 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
28d60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
28d70 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a . Furthermore,.
28d80 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f ** the [temp_sto
28d90 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
28da0 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 gma] always assu
28db0 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 mes that any str
28dc0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 ing.** that this
28dd0 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 variable points
28de0 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d to is held in m
28df0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
28e00 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rom .** [sqlite3
28e10 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 _malloc] and the
28e20 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 pragma may atte
28e30 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 mpt to free that
28e40 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 memory.** using
28e50 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e [sqlite3_free].
28e60 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 .** Hence, if th
28e70 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d is variable is m
28e80 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 odified directly
28e90 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 , either it shou
28ea0 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 ld be.** made NU
28eb0 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f LL or made to po
28ec0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 int to memory ob
28ed0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
28ee0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 ite3_malloc].**
28ef0 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 or else the use
28f00 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f of the [temp_sto
28f10 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
28f20 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 gma] should be a
28f30 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 voided..*/.SQLIT
28f40 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 E_EXTERN char *s
28f50 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
28f60 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ctory;../*.** CA
28f70 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 PI3REF: Test For
28f80 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 Auto-Commit Mod
28f90 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32 e {H12930} <S602
28fa0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
28fb0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 {autocommit mod
28fc0 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e}.**.** The sql
28fd0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d ite3_get_autocom
28fe0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 mit() interface
28ff0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
29000 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 or.** zero if t
29010 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 he given databas
29020 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
29030 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 or is not in aut
29040 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a ocommit mode,.**
29050 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 respectively.
29060 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
29070 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 is on by default
29080 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ..** Autocommit
29090 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 mode is disabled
290a0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 by a [BEGIN] st
290b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f atement..** Auto
290c0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 commit mode is r
290d0 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b e-enabled by a [
290e0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c COMMIT] or [ROLL
290f0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 BACK]..**.** If
29100 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 certain kinds of
29110 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e errors occur on
29120 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 a statement wit
29130 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 hin a multi-stat
29140 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 ement.** transac
29150 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 tion (errors inc
29160 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 luding [SQLITE_F
29170 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f ULL], [SQLITE_IO
29180 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 ERR],.** [SQLITE
29190 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 _NOMEM], [SQLITE
291a0 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c _BUSY], and [SQL
291b0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 ITE_INTERRUPT])
291c0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e then the.** tran
291d0 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 saction might be
291e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
291f0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 omatically. The
29200 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 only way to.**
29210 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 find out whether
29220 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 SQLite automati
29230 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 cally rolled bac
29240 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f k the transactio
29250 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 n after.** an er
29260 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 ror is to use th
29270 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a is function..**.
29280 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 ** If another th
29290 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 read changes the
292a0 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 autocommit stat
292b0 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 us of the databa
292c0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
292d0 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 while this rout
292e0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 ine is running,
292f0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 then the return
29300 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 value.** is unde
29310 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 fined..**.** Req
29320 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 uirements: [H129
29330 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 31] [H12932] [H1
29340 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2933] [H12934].*
29350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 /.int sqlite3_ge
29360 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c t_autocommit(sql
29370 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
29380 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 API3REF: Find Th
29390 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c e Database Handl
293a0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 e Of A Prepared
293b0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 Statement {H1312
293c0 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S60600>.**.*
293d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 * The sqlite3_db
293e0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 _handle interfac
293f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 e returns the [d
29400 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
29410 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f on] handle.** to
29420 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 which a [prepar
29430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 ed statement] be
29440 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 74 longs. The [dat
29450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
29460 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 ].** returned by
29470 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 sqlite3_db_hand
29480 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b le is the same [
29490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
294a0 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 74 68 ion] that was th
294b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
294c0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
294d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
294e0 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 ] call (or its v
294f0 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 ariants) that wa
29500 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 s used to.** cre
29510 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
29520 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 t in the first p
29530 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 lace..**.** Requ
29540 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 irements: [H1312
29550 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 3].*/.sqlite3 *s
29560 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
29570 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
29580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29590 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 : Find the next
295a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
295b0 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 nt {H13140} <S60
295c0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
295d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
295e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
295f0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 he next [prepare
29600 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 d statement] aft
29610 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f er.** pStmt asso
29620 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
29630 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
29640 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 tion] pDb. If p
29650 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 Stmt is NULL.**
29660 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 then this interf
29670 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
29680 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 inter to the fir
29690 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 st prepared stat
296a0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 ement.** associa
296b0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 ted with the dat
296c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
296d0 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 pDb. If no pre
296e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
296f0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 ** satisfies the
29700 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 conditions of t
29710 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 his routine, it
29720 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a returns NULL..**
29730 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 .** The [databas
29740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f e connection] po
29750 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c inter D in a cal
29760 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
29770 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d _next_stmt(D,S)]
29780 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 must refer to a
29790 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a n open database.
297a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e ** connection an
297b0 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 d in particular
297c0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 must not be a NU
297d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
297e0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 * Requirements:
297f0 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31 34 36 [H13143] [H13146
29800 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31 33 31 ] [H13149] [H131
29810 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 52].*/.sqlite3_s
29820 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 tmt *sqlite3_nex
29830 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a t_stmt(sqlite3 *
29840 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d pDb, sqlite3_stm
29850 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
29860 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d * CAPI3REF: Comm
29870 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 it And Rollback
29880 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c Notification Cal
29890 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 lbacks {H12950}
298a0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60400>.**.** T
298b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 he sqlite3_commi
298c0 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 t_hook() interfa
298d0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
298e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
298f0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ion to be invoke
29900 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 d whenever a tra
29910 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d nsaction is comm
29920 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 itted..** Any ca
29930 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 llback set by a
29940 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
29950 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f sqlite3_commit_
29960 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 hook().** for th
29970 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
29980 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
29990 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 erridden..** The
299a0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 sqlite3_rollbac
299b0 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 k_hook() interfa
299c0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
299d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
299e0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ion to be invoke
299f0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 d whenever a tra
29a00 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d nsaction is comm
29a10 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 itted..** Any ca
29a20 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 llback set by a
29a30 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
29a40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f sqlite3_commit_
29a50 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 hook().** for th
29a60 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
29a70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
29a80 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 erridden..** The
29a90 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 pArg argument i
29aa0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
29ab0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
29ac0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c ..** If the call
29ad0 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 back on a commit
29ae0 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 hook function r
29af0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
29b00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d .** then the com
29b10 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 mit is converted
29b20 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b into a rollback
29b30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 ..**.** If anoth
29b40 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 er function was
29b50 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 previously regis
29b60 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 tered, its.** pA
29b70 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 rg value is retu
29b80 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rned. Otherwise
29b90 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
29ba0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c d..**.** The cal
29bb0 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 lback implementa
29bc0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f tion must not do
29bd0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
29be0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
29bf0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
29c00 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
29c10 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e ed the callback.
29c20 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a Any actions.**
29c30 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 to modify the d
29c40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
29c50 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 on must be defer
29c60 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 red until after
29c70 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f the.** completio
29c80 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n of the [sqlite
29c90 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 3_step()] call t
29ca0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
29cb0 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 e commit.** or r
29cc0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 ollback hook in
29cd0 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e the first place.
29ce0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
29cf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
29d00 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
29d10 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
29d20 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
29d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
29d40 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
29d50 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
29d60 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
29d70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 h..**.** Registe
29d80 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 ring a NULL func
29d90 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 tion disables th
29da0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a e callback..**.*
29db0 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 * For the purpos
29dc0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 es of this API,
29dd0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
29de0 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 said to have be
29df0 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 en.** rolled bac
29e00 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 k if an explicit
29e10 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 "ROLLBACK" stat
29e20 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 ement is execute
29e30 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f d, or.** an erro
29e40 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 r or constraint
29e50 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 causes an implic
29e60 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f it rollback to o
29e70 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c ccur..** The rol
29e80 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 lback callback i
29e90 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 s not invoked if
29ea0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
29eb0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c s.** automatical
29ec0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ly rolled back b
29ed0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 ecause the datab
29ee0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
29ef0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 s closed..** The
29f00 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 rollback callba
29f10 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 ck is not invoke
29f20 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 d if a transacti
29f30 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 on is.** rolled
29f40 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 back because a c
29f50 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 ommit callback r
29f60 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f eturned non-zero
29f70 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 ..** <todo> Chec
29f80 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f k on this </todo
29f90 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d >.**.** Requirem
29fa0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31 ents:.** [H12951
29fb0 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39 ] [H12952] [H129
29fc0 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31 53] [H12954] [H1
29fd0 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31 2955].** [H12961
29fe0 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39 ] [H12962] [H129
29ff0 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a 63] [H12964].*/.
2a000 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2a010 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 mmit_hook(sqlite
2a020 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 3*, int(*)(void*
2a030 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 ), void*);.void
2a040 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 *sqlite3_rollbac
2a050 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c k_hook(sqlite3*,
2a060 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 void(*)(void *)
2a070 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
2a080 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 CAPI3REF: Data
2a090 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 Change Notificat
2a0a0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 ion Callbacks {H
2a0b0 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 12970} <S60400>.
2a0c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2a0d0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 3_update_hook()
2a0e0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
2a0f0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
2a100 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 unction.** with
2a110 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2a120 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 nnection] identi
2a130 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
2a140 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f t argument.** to
2a150 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
2a160 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 ever a row is up
2a170 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
2a180 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 or deleted..** A
2a190 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
2a1a0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
2a1b0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 ll to this funct
2a1c0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 ion.** for the s
2a1d0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
2a1e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 nection is overr
2a1f0 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 idden..**.** The
2a200 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2a210 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
2a220 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f the function to
2a230 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a invoke when a.*
2a240 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 * row is updated
2a250 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 , inserted or de
2a260 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 leted..** The fi
2a270 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
2a280 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
2a290 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 a copy of the th
2a2a0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ird argument.**
2a2b0 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 to sqlite3_updat
2a2c0 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 e_hook()..** The
2a2d0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b second callback
2a2e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 argument is one
2a2f0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 of [SQLITE_INSE
2a300 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c RT], [SQLITE_DEL
2a310 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c ETE],.** or [SQL
2a320 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 ITE_UPDATE], dep
2a330 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 ending on the op
2a340 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 eration that cau
2a350 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b sed the callback
2a360 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 .** to be invoke
2a370 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 d..** The third
2a380 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d and fourth argum
2a390 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c ents to the call
2a3a0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 back contain poi
2a3b0 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 nters to the.**
2a3c0 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 database and tab
2a3d0 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 le name containi
2a3e0 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 ng the affected
2a3f0 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 row..** The fina
2a400 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d l callback param
2a410 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 eter is the [row
2a420 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a id] of the row..
2a430 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f ** In the case o
2a440 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 f an update, thi
2a450 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d s is the [rowid]
2a460 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 after the updat
2a470 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a e takes place..*
2a480 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 *.** The update
2a490 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f hook is not invo
2a4a0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 ked when interna
2a4b0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 l system tables
2a4c0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 are.** modified
2a4d0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 (i.e. sqlite_mas
2a4e0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 ter and sqlite_s
2a4f0 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 equence)..**.**
2a500 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 The update hook
2a510 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
2a520 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
2a530 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
2a540 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
2a550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a560 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
2a570 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 update hook. A
2a580 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f ny actions.** to
2a590 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
2a5a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a5b0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 must be deferred
2a5c0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 until after the
2a5d0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f .** completion o
2a5e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 f the [sqlite3_s
2a5f0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 tep()] call that
2a600 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 triggered the u
2a610 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e pdate hook..** N
2a620 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
2a630 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2a640 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
2a650 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
2a660 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
2a670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
2a680 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
2a690 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
2a6a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
2a6b0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 .** If another f
2a6c0 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 unction was prev
2a6d0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 iously registere
2a6e0 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 d, its pArg valu
2a6f0 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 e.** is returned
2a700 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c . Otherwise NUL
2a710 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a L is returned..*
2a720 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2a730 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b s:.** [H12971] [
2a740 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 5d H12973] [H12975]
2a750 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 37 [H12977] [H1297
2a760 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 32 9] [H12981] [H12
2a770 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f 983] [H12986].*/
2a780 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
2a790 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 pdate_hook(. sq
2a7a0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 lite3*, . void(
2a7b0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 *)(void *,int ,c
2a7c0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 har const *,char
2a7d0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 const *,sqlite3
2a7e0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a _int64),. void*
2a7f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
2a800 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
2a810 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 isable Shared Pa
2a820 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 ger Cache {H1033
2a830 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 0} <S30900>.** K
2a840 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 EYWORDS: {shared
2a850 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 cache} {shared
2a860 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a cache mode}.**.*
2a870 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 * This routine e
2a880 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
2a890 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f es the sharing o
2a8a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
2a8b0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 ache.** and sche
2a8c0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ma data structur
2a8d0 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 es between [data
2a8e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a8f0 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a | connections].*
2a900 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 * to the same da
2a910 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 tabase. Sharing
2a920 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 is enabled if th
2a930 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 e argument is tr
2a940 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c ue.** and disabl
2a950 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
2a960 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a nt is false..**.
2a970 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 ** Cache sharing
2a980 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 is enabled and
2a990 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 disabled for an
2a9a0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a entire process..
2a9b0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 ** This is a cha
2a9c0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 nge as of SQLite
2a9d0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 version 3.5.0.
2a9e0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e In prior version
2a9f0 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 s of SQLite,.**
2aa00 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 sharing was enab
2aa10 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 led or disabled
2aa20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 for each thread
2aa30 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a separately..**.*
2aa40 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 * The cache shar
2aa50 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 ing mode set by
2aa60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 this interface e
2aa70 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 ffects all subse
2aa80 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 quent.** calls t
2aa90 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
2aaa0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2aab0 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 n_v2()], and [sq
2aac0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
2aad0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 .** Existing dat
2aae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2aaf0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 s continue use t
2ab00 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a he sharing mode.
2ab10 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 ** that was in e
2ab20 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d ffect at the tim
2ab30 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e e they were open
2ab40 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 ed..**.** Virtua
2ab50 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 l tables cannot
2ab60 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 be used with a s
2ab70 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 hared cache. Wh
2ab80 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 en shared.** cac
2ab90 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 he is enabled, t
2aba0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2abb0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 te_module()] API
2abc0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 used to registe
2abd0 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 r.** virtual tab
2abe0 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 les will always
2abf0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e return an error.
2ac00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2ac10 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
2ac20 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 ITE_OK] if share
2ac30 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 d cache was enab
2ac40 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a led or disabled.
2ac50 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
2ac60 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 An [error code
2ac70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 ] is returned ot
2ac80 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 herwise..**.** S
2ac90 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 hared cache is d
2aca0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
2acb0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 lt. But this mig
2acc0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 ht change in.**
2acd0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
2ace0 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c of SQLite. Appl
2acf0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 ications that ca
2ad00 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a re about shared.
2ad10 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 ** cache setting
2ad20 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 should set it e
2ad30 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a xplicitly..**.**
2ad40 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c See Also: [SQL
2ad50 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 ite Shared-Cache
2ad60 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 Mode].**.** Req
2ad70 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33 uirements: [H103
2ad80 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31 31] [H10336] [H1
2ad90 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a 0337] [H10339].*
2ada0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e /.int sqlite3_en
2adb0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
2adc0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e(int);../*.** C
2add0 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 API3REF: Attempt
2ade0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 To Free Heap Me
2adf0 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 mory {H17340} <S
2ae00 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30220>.**.** The
2ae10 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
2ae20 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 _memory() interf
2ae30 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
2ae40 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 free N bytes.**
2ae50 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 of heap memory b
2ae60 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e y deallocating n
2ae70 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d on-essential mem
2ae80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a ory allocations.
2ae90 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 ** held by the d
2aea0 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e atabase library.
2aeb0 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 {END} Memory u
2aec0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 sed to cache dat
2aed0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 abase.** pages t
2aee0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 o improve perfor
2aef0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d mance is an exam
2af00 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e ple of non-essen
2af10 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 tial memory..**
2af20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
2af30 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 memory() returns
2af40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2af50 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 ytes actually fr
2af60 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 eed,.** which mi
2af70 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c ght be more or l
2af80 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f ess than the amo
2af90 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a unt requested..*
2afa0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2afb0 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37 s: [H17341] [H17
2afc0 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 342].*/.int sqli
2afd0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2afe0 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ry(int);../*.**
2aff0 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 CAPI3REF: Impose
2b000 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 A Limit On Heap
2b010 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c Size {H17350} <
2b020 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30220>.**.** Th
2b030 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 e sqlite3_soft_h
2b040 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 eap_limit() inte
2b050 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 rface places a "
2b060 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f soft" limit.** o
2b070 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 n the amount of
2b080 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 heap memory that
2b090 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 may be allocate
2b0a0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 d by SQLite..**
2b0b0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 If an internal a
2b0c0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 llocation is req
2b0d0 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c uested that woul
2b0e0 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 d exceed the.**
2b0f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c soft heap limit,
2b100 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
2b110 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 e_memory()] is i
2b120 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a nvoked one or.**
2b130 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 more times to f
2b140 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 ree up some spac
2b150 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c e before the all
2b160 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f ocation is perfo
2b170 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rmed..**.** The
2b180 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 limit is called
2b190 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 "soft", because
2b1a0 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 if [sqlite3_rele
2b1b0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a ase_memory()].**
2b1c0 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 cannot free suf
2b1d0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 ficient memory t
2b1e0 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 o prevent the li
2b1f0 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 mit from being e
2b200 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 xceeded,.** the
2b210 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 memory is alloca
2b220 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 ted anyway and t
2b230 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 he current opera
2b240 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a tion proceeds..*
2b250 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 *.** A negative
2b260 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f or zero value fo
2b270 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 r N means that t
2b280 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 here is no soft
2b290 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a heap limit and.*
2b2a0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 * [sqlite3_relea
2b2b0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c se_memory()] wil
2b2c0 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 l only be called
2b2d0 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 when memory is
2b2e0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 exhausted..** Th
2b2f0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 e default value
2b300 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 for the soft hea
2b310 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e p limit is zero.
2b320 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 .**.** SQLite ma
2b330 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 kes a best effor
2b340 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 t to honor the s
2b350 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a oft heap limit..
2b360 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f ** But if the so
2b370 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 ft heap limit ca
2b380 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c nnot be honored,
2b390 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a execution will.
2b3a0 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 ** continue with
2b3b0 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 out error or not
2b3c0 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 ification. This
2b3d0 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 is why the limi
2b3e0 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 t is.** called a
2b3f0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 "soft" limit.
2b400 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f It is advisory o
2b410 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 nly..**.** Prior
2b420 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 to SQLite versi
2b430 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 on 3.5.0, this r
2b440 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 outine only cons
2b450 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f trained the memo
2b460 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 ry.** allocated
2b470 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 by a single thre
2b480 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 ad - the same th
2b490 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 read in which th
2b4a0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 is routine.** ru
2b4b0 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 ns. Beginning w
2b4c0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 ith SQLite versi
2b4d0 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f on 3.5.0, the so
2b4e0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
2b4f0 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 .** applied to a
2b500 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 ll threads. The
2b510 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 value specified
2b520 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 for the soft hea
2b530 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e p limit.** is an
2b540 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 upper bound on
2b550 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 the total memory
2b560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 allocation for
2b570 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a all threads. In.
2b580 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 ** version 3.5.0
2b590 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 there is no mec
2b5a0 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 hanism for limit
2b5b0 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 ing the heap usa
2b5c0 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 ge for.** indivi
2b5d0 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a dual threads..**
2b5e0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
2b5f0 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48 :.** [H16351] [H
2b600 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20 16352] [H16353]
2b610 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35 [H16354] [H16355
2b620 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f ] [H16358].*/.vo
2b630 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f id sqlite3_soft_
2b640 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b heap_limit(int);
2b650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2b660 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 : Extract Metada
2b670 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d ta About A Colum
2b680 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31 n Of A Table {H1
2b690 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2850} <S60300>.*
2b6a0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
2b6b0 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 e returns metada
2b6c0 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 ta about a speci
2b6d0 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 fic column of a
2b6e0 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 specific.** data
2b6f0 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 base table acces
2b700 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 sible using the
2b710 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2b720 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 tion] handle.**
2b730 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
2b740 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 rst function arg
2b750 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
2b760 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 column is ident
2b770 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 ified by the sec
2b780 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 ond, third and f
2b790 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
2b7a0 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 to.** this func
2b7b0 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 tion. The second
2b7c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 parameter is ei
2b7d0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 ther the name of
2b7e0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
2b7f0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 (i.e. "main", "
2b800 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 temp" or an atta
2b810 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 ched database) c
2b820 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 ontaining the sp
2b830 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 ecified.** table
2b840 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 or NULL. If it
2b850 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c is NULL, then al
2b860 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 l attached datab
2b870 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 ases are searche
2b880 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 d.** for the tab
2b890 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d le using the sam
2b8a0 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 e algorithm used
2b8b0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 by the database
2b8c0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 engine to.** re
2b8d0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 solve unqualifie
2b8e0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 d table referenc
2b8f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 es..**.** The th
2b900 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
2b910 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 arameters to thi
2b920 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 s function are t
2b930 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c he table and col
2b940 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 umn.** name of t
2b950 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d he desired colum
2b960 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
2b970 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 Neither of thes
2b980 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 e parameters.**
2b990 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a may be NULL..**.
2b9a0 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72 ** Metadata is r
2b9b0 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 eturned by writi
2b9c0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 ng to the memory
2b9d0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 locations passe
2b9e0 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 d as the 5th.**
2b9f0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 and subsequent p
2ba00 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 arameters to thi
2ba10 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 s function. Any
2ba20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e of these argumen
2ba30 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c ts may be.** NUL
2ba40 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 L, in which case
2ba50 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
2ba60 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 ng element of me
2ba70 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 tadata is omitte
2ba80 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 d..**.** <blockq
2ba90 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 uote>.** <table
2baa0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c border="1">.** <
2bab0 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 tr><th> Paramete
2bac0 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 r <th> Output<br
2bad0 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 >Type <th> Desc
2bae0 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 ription.**.** <t
2baf0 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 r><td> 5th <td>
2bb00 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e const char* <td>
2bb10 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 Data type.** <t
2bb20 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 r><td> 6th <td>
2bb30 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e const char* <td>
2bb40 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 Name of default
2bb50 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
2bb60 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nce.** <tr><td>
2bb70 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 7th <td> int
2bb80 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 <td> True i
2bb90 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e f column has a N
2bba0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 OT NULL constrai
2bbb0 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 nt.** <tr><td> 8
2bbc0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 th <td> int
2bbd0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 <td> True if
2bbe0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 column is part
2bbf0 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b of the PRIMARY K
2bc00 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 EY.** <tr><td> 9
2bc10 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 th <td> int
2bc20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 <td> True if
2bc30 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f column is [AUTO
2bc40 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f INCREMENT].** </
2bc50 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 table>.** </bloc
2bc60 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
2bc70 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 e memory pointed
2bc80 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 to by the chara
2bc90 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 cter pointers re
2bca0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a turned for the.*
2bcb0 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 * declaration ty
2bcc0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e pe and collation
2bcd0 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c sequence is val
2bce0 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 id only until th
2bcf0 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 e next.** call t
2bd00 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 o any SQLite API
2bd10 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
2bd20 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 If the specifie
2bd30 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 d table is actua
2bd40 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b lly a view, an [
2bd50 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
2bd60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
2bd70 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 f the specified
2bd80 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 column is "rowid
2bd90 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f ", "oid" or "_ro
2bda0 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 wid_" and an.**
2bdb0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
2bdc0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 KEY] column has
2bdd0 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 been explicitly
2bde0 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 declared, then
2bdf0 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 the output.** pa
2be00 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 rameters are set
2be10 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 for the explici
2be20 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c tly declared col
2be30 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 umn. If there is
2be40 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c no.** explicitl
2be50 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 y declared [INTE
2be60 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d GER PRIMARY KEY]
2be70 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 column, then th
2be80 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
2be90 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 meters are set a
2bea0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
2beb0 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 <pre>.** da
2bec0 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 ta type: "INTEGE
2bed0 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 R".** collat
2bee0 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 ion sequence: "B
2bef0 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f INARY".** no
2bf00 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 t null: 0.**
2bf10 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a primary key: 1.
2bf20 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 ** auto incr
2bf30 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 ement: 0.** </pr
2bf40 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 e>.**.** This fu
2bf50 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 nction may load
2bf60 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 one or more sche
2bf70 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 mas from databas
2bf80 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a e files. If an.*
2bf90 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 * error occurs d
2bfa0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 uring this proce
2bfb0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 ss, or if the re
2bfc0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 quested table or
2bfd0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f column.** canno
2bfe0 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b t be found, an [
2bff0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
2c000 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 eturned and an e
2c010 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 rror message lef
2c020 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 t.** in the [dat
2c030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2c040 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 ] (to be retriev
2c050 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 ed using sqlite3
2c060 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a _errmsg())..**.*
2c070 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e * This API is on
2c080 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
2c090 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
2c0a0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
2c0b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
2c0c0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 BLE_COLUMN_METAD
2c0d0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 ATA] C-preproces
2c0e0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e sor symbol defin
2c0f0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
2c100 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f e3_table_column_
2c110 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 metadata(. sqli
2c120 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2c130 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 /* Conne
2c140 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a ction handle */.
2c150 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 const char *zD
2c160 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a bName, /*
2c170 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f Database name o
2c180 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 r NULL */. cons
2c190 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 t char *zTableNa
2c1a0 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 me, /* Table
2c1b0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 name */. const
2c1c0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 char *zColumnNa
2c1d0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e me, /* Column
2c1e0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 name */. char
2c1f0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 const **pzDataTy
2c200 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 pe, /* OUTPUT
2c210 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 : Declared data
2c220 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 type */. char c
2c230 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 onst **pzCollSeq
2c240 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a , /* OUTPUT:
2c250 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 Collation seque
2c260 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e nce name */. in
2c270 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 t *pNotNull,
2c280 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
2c290 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 PUT: True if NOT
2c2a0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 NULL constraint
2c2b0 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 exists */. int
2c2c0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 *pPrimaryKey,
2c2d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 /* OUTP
2c2e0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 UT: True if colu
2c2f0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f mn part of PK */
2c300 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 . int *pAutoinc
2c310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2c320 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 * OUTPUT: True i
2c330 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f f column is auto
2c340 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b -increment */.);
2c350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2c360 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 : Load An Extens
2c370 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 ion {H12600} <S2
2c380 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0500>.**.** This
2c390 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 interface loads
2c3a0 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e an SQLite exten
2c3b0 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f sion library fro
2c3c0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 m the named file
2c3d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d ..**.** {H12601}
2c3e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 The sqlite3_loa
2c3f0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
2c400 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
2c410 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 to load an.**
2c420 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 SQLite e
2c430 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 xtension library
2c440 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 contained in th
2c450 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a e file zFile..**
2c460 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 .** {H12602} The
2c470 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 entry point is
2c480 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 zProc..**.** {H1
2c490 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 2603} zProc may
2c4a0 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 be 0, in which c
2c4b0 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 ase the name of
2c4c0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a the entry point.
2c4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 ** defa
2c4e0 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 ults to "sqlite3
2c4f0 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 _extension_init"
2c500 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d ..**.** {H12604}
2c510 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 The sqlite3_loa
2c520 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
2c530 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 terface shall re
2c540 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
2c550 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
2c560 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c success and [SQL
2c570 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f ITE_ERROR] if so
2c580 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f mething goes wro
2c590 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 ng..**.** {H1260
2c5a0 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 5} If an error o
2c5b0 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d ccurs and pzErrM
2c5c0 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 sg is not 0, the
2c5d0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
2c5e0 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f [sqlite3_load_
2c5f0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 extension()] int
2c600 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 erface shall att
2c610 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 empt to.**
2c620 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d fill *pzErrM
2c630 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 sg with error me
2c640 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 ssage text store
2c650 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 d in memory.**
2c660 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 obtained
2c670 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
2c680 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 alloc()]. {END}
2c690 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e The calling fun
2c6a0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
2c6b0 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 should free th
2c6c0 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c is memory by cal
2c6d0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 ling [sqlite3_fr
2c6e0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ee()]..**.** {H1
2c6f0 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 2606} Extension
2c700 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 loading must be
2c710 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a enabled using.**
2c720 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
2c730 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
2c740 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f xtension()] prio
2c750 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 r to calling thi
2c760 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 s API,.**
2c770 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 otherwise an
2c780 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
2c790 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 turned..*/.int s
2c7a0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
2c7b0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 nsion(. sqlite3
2c7c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
2c7d0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e * Load the exten
2c7e0 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 sion into this d
2c7f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2c800 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 on */. const ch
2c810 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a ar *zFile, /*
2c820 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 Name of the sha
2c830 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 red library cont
2c840 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e aining extension
2c850 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2c860 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 *zProc, /* E
2c870 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 ntry point. Der
2c880 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 ived from zFile
2c890 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a if 0 */. char *
2c8a0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 *pzErrMsg
2c8b0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 /* Put error mes
2c8c0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 sage here if not
2c8d0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 0 */.);../*.**
2c8e0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
2c8f0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
2c900 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 nsion Loading {H
2c910 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 12620} <S20500>.
2c920 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 **.** So as not
2c930 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 to open security
2c940 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 holes in older
2c950 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
2c960 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 t are.** unprepa
2c970 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 red to deal with
2c980 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 extension loadi
2c990 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 ng, and as a mea
2c9a0 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a ns of disabling.
2c9b0 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 ** extension loa
2c9c0 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 ding while evalu
2c9d0 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 ating user-enter
2c9e0 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c ed SQL, the foll
2c9f0 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 owing API.** is
2ca00 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e provided to turn
2ca10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
2ca20 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 ad_extension()]
2ca30 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 mechanism on and
2ca40 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 off..**.** Exte
2ca50 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 nsion loading is
2ca60 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e off by default.
2ca70 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 See ticket #186
2ca80 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 3..**.** {H12621
2ca90 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 } Call the sqlit
2caa0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
2cab0 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 xtension() routi
2cac0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 ne with onoff==1
2cad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 .** to
2cae0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c turn extension l
2caf0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 oading on and ca
2cb00 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 ll it with onoff
2cb10 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 ==0 to turn.**
2cb20 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20 it back
2cb30 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a off again..**.**
2cb40 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73 {H12622} Extens
2cb50 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f ion loading is o
2cb60 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ff by default..*
2cb70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e /.int sqlite3_en
2cb80 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
2cb90 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c ion(sqlite3 *db,
2cba0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
2cbb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
2cbc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 tomatically Load
2cbd0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b An Extensions {
2cbe0 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e H12640} <S20500>
2cbf0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
2cc00 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 can be invoked a
2cc10 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 t program startu
2cc20 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 p in order to re
2cc30 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 gister.** one or
2cc40 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 more statically
2cc50 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f linked extensio
2cc60 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 ns that will be
2cc70 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 available.** to
2cc80 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73 all new [databas
2cc90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 e connections].
2cca0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 {END}.**.** This
2ccb0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
2ccc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2ccd0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e extension in an
2cce0 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a array that is.*
2ccf0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 * obtained from
2cd00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
2cd10 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20 )]. If you run
2cd20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 a memory leak ch
2cd30 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 ecker.** on your
2cd40 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 program and it
2cd50 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 reports a leak b
2cd60 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61 ecause of this a
2cd70 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 rray, invoke.**
2cd80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 [sqlite3_reset_a
2cd90 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d uto_extension()]
2cda0 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f prior to shutdo
2cdb0 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d wn to free the m
2cdc0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 emory..**.** {H1
2cdd0 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 2641} This funct
2cde0 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e ion registers an
2cdf0 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 extension entry
2ce00 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a point that is.*
2ce10 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d * autom
2ce20 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 atically invoked
2ce30 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 whenever a new
2ce40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2ce50 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 tion].**
2ce60 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e is opened usin
2ce70 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 g [sqlite3_open(
2ce80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2ce90 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 n16()],.**
2cea0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f or [sqlite3_
2ceb0 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a open_v2()]..**.*
2cec0 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69 * {H12642} Dupli
2ced0 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 cate extensions
2cee0 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 are detected so
2cef0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 calling this rou
2cf00 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 tine.**
2cf10 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
2cf20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 with the same ex
2cf30 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c tension is harml
2cf40 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ess..**.** {H126
2cf50 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 43} This routine
2cf60 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 stores a pointe
2cf70 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 r to the extensi
2cf80 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a on in an array.*
2cf90 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 * that
2cfa0 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d is obtained from
2cfb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2cfc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ()]..**.** {H126
2cfd0 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 44} Automatic ex
2cfe0 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 tensions apply a
2cff0 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 cross all thread
2d000 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
2d010 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 3_auto_extension
2d020 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f (void (*xEntryPo
2d030 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a int)(void));../*
2d040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
2d050 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 set Automatic Ex
2d060 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 tension Loading
2d070 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30 {H12660} <S20500
2d080 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
2d090 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 ction disables a
2d0a0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ll previously re
2d0b0 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 gistered automat
2d0c0 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 ic.** extensions
2d0d0 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f . {END} It undo
2d0e0 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 es the effect of
2d0f0 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 all prior.** [s
2d100 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
2d110 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a nsion()] calls..
2d120 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 **.** {H12661} T
2d130 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 his function dis
2d140 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f ables all previo
2d150 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a usly registered.
2d160 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f ** auto
2d170 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 matic extensions
2d180 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d ..**.** {H12662}
2d190 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 This function d
2d1a0 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 isables automati
2d1b0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 c extensions in
2d1c0 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a all threads..*/.
2d1d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
2d1e0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f et_auto_extensio
2d1f0 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a n(void);../*.***
2d200 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c *** EXPERIMENTAL
2d210 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 - subject to ch
2d220 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 ange without not
2d230 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ice ************
2d240 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 **.**.** The int
2d250 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 erface to the vi
2d260 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
2d270 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 anism is current
2d280 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a ly considered.**
2d290 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e to be experimen
2d2a0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 tal. The interf
2d2b0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 ace might change
2d2c0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 in incompatible
2d2d0 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 ways..** If thi
2d2e0 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 s is a problem f
2d2f0 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 or you, do not u
2d300 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 se the interface
2d310 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a at this time..*
2d320 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 *.** When the vi
2d330 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
2d340 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 anism stabilizes
2d350 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 , we will declar
2d360 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 e the.** interfa
2d370 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 ce fixed, suppor
2d380 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c t it indefinitel
2d390 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 y, and remove th
2d3a0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a is comment..*/..
2d3b0 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 /*.** Structures
2d3c0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 used by the vir
2d3d0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 tual table inter
2d3e0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 face.*/.typedef
2d3f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2d400 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 tab sqlite3_vtab
2d410 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
2d420 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
2d430 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 nfo sqlite3_inde
2d440 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 x_info;.typedef
2d450 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2d460 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 tab_cursor sqlit
2d470 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a e3_vtab_cursor;.
2d480 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
2d490 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 qlite3_module sq
2d4a0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f lite3_module;../
2d4b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
2d4c0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a irtual Table Obj
2d4d0 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 ect {H18000} <S2
2d4e0 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
2d4f0 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c S: sqlite3_modul
2d500 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 e.** EXPERIMENTA
2d510 4c 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 L.**.** A module
2d520 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 is a class of v
2d530 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 irtual tables.
2d540 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 Each module is d
2d550 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 efined.** by an
2d560 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
2d570 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 following struct
2d580 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 ure. This struc
2d590 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a ture consists.**
2d5a0 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f mostly of metho
2d5b0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
2d5c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e e..**.** This in
2d5d0 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 terface is exper
2d5e0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 imental and is s
2d5f0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
2d600 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 or.** removal i
2d610 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
2d620 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a s of SQLite..*/.
2d630 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
2d640 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 odule {. int iV
2d650 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
2d660 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 xCreate)(sqlite3
2d670 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 *, void *pAux,.
2d680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
2d690 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 t argc, const ch
2d6a0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a ar *const*argv,.
2d6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 s
2d6c0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 qlite3_vtab **pp
2d6d0 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 VTab, char**);.
2d6e0 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 int (*xConnect)
2d6f0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 (sqlite3*, void
2d700 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 *pAux,.
2d710 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 int argc,
2d720 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 const char *cons
2d730 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 t*argv,.
2d740 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 sqlite3_v
2d750 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 tab **ppVTab, ch
2d760 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ar**);. int (*x
2d770 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 BestIndex)(sqlit
2d780 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 e3_vtab *pVTab,
2d790 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
2d7a0 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 fo*);. int (*xD
2d7b0 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 isconnect)(sqlit
2d7c0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
2d7d0 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f . int (*xDestro
2d7e0 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 y)(sqlite3_vtab
2d7f0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
2d800 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
2d810 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c vtab *pVTab, sql
2d820 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
2d830 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 **ppCursor);.
2d840 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 int (*xClose)(sq
2d850 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
2d860 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 r*);. int (*xFi
2d870 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 lter)(sqlite3_vt
2d880 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 ab_cursor*, int
2d890 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 idxNum, const ch
2d8a0 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 ar *idxStr,.
2d8b0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 int
2d8c0 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 argc, sqlite3_va
2d8d0 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 lue **argv);. i
2d8e0 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 nt (*xNext)(sqli
2d8f0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
2d900 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 );. int (*xEof)
2d910 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
2d920 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a rsor*);. int (*
2d930 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 xColumn)(sqlite3
2d940 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 _vtab_cursor*, s
2d950 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2d960 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
2d970 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 Rowid)(sqlite3_v
2d980 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c tab_cursor*, sql
2d990 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 ite3_int64 *pRow
2d9a0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 id);. int (*xUp
2d9b0 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 date)(sqlite3_vt
2d9c0 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 ab *, int, sqlit
2d9d0 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c e3_value **, sql
2d9e0 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 ite3_int64 *);.
2d9f0 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 int (*xBegin)(s
2da00 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2da10 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ab);. int (*xSy
2da20 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 nc)(sqlite3_vtab
2da30 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 *pVTab);. int
2da40 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 (*xCommit)(sqlit
2da50 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
2da60 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 . int (*xRollba
2da70 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 ck)(sqlite3_vtab
2da80 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 *pVTab);. int
2da90 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 (*xFindFunction)
2daa0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2dab0 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 Vtab, int nArg,
2dac0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
2dad0 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 e,.
2dae0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 void (
2daf0 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 **pxFunc)(sqlite
2db00 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
2db10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
2db20 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
2db30 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 void **p
2db40 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 pArg);. int (*x
2db50 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f Rename)(sqlite3_
2db60 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e vtab *pVtab, con
2db70 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a st char *zNew);.
2db80 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
2db90 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c EF: Virtual Tabl
2dba0 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 e Indexing Infor
2dbb0 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20 mation {H18100}
2dbc0 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S20400>.** KEYW
2dbd0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e ORDS: sqlite3_in
2dbe0 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 dex_info.** EXPE
2dbf0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
2dc00 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 he sqlite3_index
2dc10 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 _info structure
2dc20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 and its substruc
2dc30 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f tures is used to
2dc40 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 .** pass informa
2dc50 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 tion into and re
2dc60 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 ceive the reply
2dc70 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e from the xBestIn
2dc80 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 dex.** method of
2dc90 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 an sqlite3_modu
2dca0 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 le. The fields
2dcb0 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a under **Inputs**
2dcc0 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 are the.** inpu
2dcd0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 ts to xBestIndex
2dce0 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e and are read-on
2dcf0 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 ly. xBestIndex
2dd00 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 inserts its.** r
2dd10 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 esults into the
2dd20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c **Outputs** fiel
2dd30 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 ds..**.** The aC
2dd40 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 onstraint[] arra
2dd50 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 y records WHERE
2dd60 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e clause constrain
2dd70 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a ts of the form:.
2dd80 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d **.** <pre>colum
2dd90 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a n OP expr</pre>.
2dda0 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 **.** where OP i
2ddb0 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d s =, <, <=
2ddc0 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d , >, or >=
2ddd0 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 . The particula
2dde0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a r operator is.**
2ddf0 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 stored in aCons
2de00 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 traint[].op. Th
2de10 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
2de20 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 olumn is stored
2de30 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e in.** aConstrain
2de40 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 t[].iColumn. aC
2de50 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 onstraint[].usab
2de60 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 le is TRUE if th
2de70 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 e.** expr on the
2de80 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 right-hand side
2de90 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 can be evaluate
2dea0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 d (and thus the
2deb0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 constraint.** is
2dec0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c usable) and fal
2ded0 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e se if it cannot.
2dee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d .**.** The optim
2def0 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c izer automatical
2df00 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 ly inverts terms
2df10 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 of the form "ex
2df20 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a pr OP column".**
2df30 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 and makes other
2df40 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 simplifications
2df50 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c to the WHERE cl
2df60 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d ause in an attem
2df70 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 pt to.** get as
2df80 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 many WHERE claus
2df90 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 e terms into the
2dfa0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 form shown abov
2dfb0 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a e as possible..*
2dfc0 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e * The aConstrain
2dfd0 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 t[] array only r
2dfe0 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 eports WHERE cla
2dff0 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 use terms in the
2e000 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d correct.** form
2e010 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 that refer to t
2e020 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 he particular vi
2e030 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e rtual table bein
2e040 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a g queried..**.**
2e050 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f Information abo
2e060 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 ut the ORDER BY
2e070 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 clause is stored
2e080 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a in aOrderBy[]..
2e090 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 ** Each term of
2e0a0 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 aOrderBy records
2e0b0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 a column of the
2e0c0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 ORDER BY clause
2e0d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 ..**.** The xBes
2e0e0 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 tIndex method mu
2e0f0 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 st fill aConstra
2e100 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 intUsage[] with
2e110 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 information.** a
2e120 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 bout what parame
2e130 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 ters to pass to
2e140 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 xFilter. If arg
2e150 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a vIndex>0 then.**
2e160 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 the right-hand
2e170 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 side of the corr
2e180 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 esponding aConst
2e190 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 raint[] is evalu
2e1a0 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f ated.** and beco
2e1b0 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 mes the argvInde
2e1c0 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 x-th entry in ar
2e1d0 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 gv. If aConstra
2e1e0 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a intUsage[].omit.
2e1f0 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e ** is true, then
2e200 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
2e210 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 is assumed to be
2e220 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 fully handled b
2e230 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c y the.** virtual
2e240 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f table and is no
2e250 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 t checked again
2e260 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a by SQLite..**.**
2e270 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 The idxNum and
2e280 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 idxPtr values ar
2e290 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 e recorded and p
2e2a0 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 assed into xFilt
2e2b0 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 er..** sqlite3_f
2e2c0 72 65 65 28 29 20 69 73 20 75 73 65 64 20 74 6f ree() is used to
2e2d0 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 free idxPtr if
2e2e0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 needToFreeIdxPtr
2e2f0 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 is true..**.**
2e300 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 The orderByConsu
2e310 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f med means that o
2e320 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 utput from xFilt
2e330 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e er will occur in
2e340 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 .** the correct
2e350 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 order to satisfy
2e360 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
2e370 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 ause so that no
2e380 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 separate.** sort
2e390 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75 ing step is requ
2e3a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ired..**.** The
2e3b0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 estimatedCost va
2e3c0 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 lue is an estima
2e3d0 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f te of the cost o
2e3e0 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 f doing the.** p
2e3f0 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 articular lookup
2e400 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f . A full scan o
2e410 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e f a table with N
2e420 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 entries should
2e430 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f have.** a cost o
2e440 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 f N. A binary s
2e450 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 earch of a table
2e460 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 of N entries sh
2e470 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 ould have a.** c
2e480 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 ost of approxima
2e490 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2a 0a tely log(N)..**.
2e4a0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
2e4b0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 e is experimenta
2e4c0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 l and is subject
2e4d0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a to change or.**
2e4e0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 removal in futu
2e4f0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
2e500 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 QLite..*/.struct
2e510 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
2e520 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 nfo {. /* Input
2e530 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 s */. int nCons
2e540 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 traint;
2e550 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 /* Number of e
2e560 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 ntries in aConst
2e570 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 raint */. struc
2e580 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
2e590 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 constraint {.
2e5a0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 int iColumn;
2e5b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
2e5c0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 olumn on left-ha
2e5d0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 nd side of const
2e5e0 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e raint */. un
2e5f0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 signed char op;
2e600 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 /* Const
2e610 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a raint operator *
2e620 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 /. unsigned
2e630 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 char usable;
2e640 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 /* True if this
2e650 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 constraint is u
2e660 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e sable */. in
2e670 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 t iTermOffset;
2e680 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 /* Used
2e690 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 internally - xBe
2e6a0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 stIndex should i
2e6b0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 gnore */. } *aC
2e6c0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 onstraint;
2e6d0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f /* Table o
2e6e0 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 f WHERE clause c
2e6f0 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 onstraints */.
2e700 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 int nOrderBy;
2e710 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
2e720 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e mber of terms in
2e730 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
2e740 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 ause */. struct
2e750 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f sqlite3_index_o
2e760 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e rderby {. in
2e770 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 t iColumn;
2e780 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d /* Colum
2e790 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 n number */.
2e7a0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 unsigned char d
2e7b0 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 esc; /* Tr
2e7c0 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 ue for DESC. Fa
2e7d0 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a lse for ASC. */.
2e7e0 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 } *aOrderBy;
2e7f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2e800 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 The ORDER BY cla
2e810 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 use */. /* Outp
2e820 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 uts */. struct
2e830 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f sqlite3_index_co
2e840 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b nstraint_usage {
2e850 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 . int argvInd
2e860 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a ex; /*
2e870 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 if >0, constrai
2e880 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 nt is part of ar
2e890 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f gv to xFilter */
2e8a0 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 . unsigned ch
2e8b0 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a ar omit; /*
2e8c0 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 Do not code a t
2e8d0 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e est for this con
2e8e0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a straint */. } *
2e8f0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
2e900 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 ;. int idxNum;
2e910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2e920 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f * Number used to
2e930 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e identify the in
2e940 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 dex */. char *i
2e950 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 dxStr;
2e960 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 /* String, p
2e970 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 ossibly obtained
2e980 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
2e990 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 lloc */. int ne
2e9a0 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 edToFreeIdxStr;
2e9b0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 /* Free idx
2e9c0 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 Str using sqlite
2e9d0 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 3_free() if true
2e9e0 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 */. int orderB
2e9f0 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 yConsumed;
2ea00 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 /* True if outp
2ea10 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 ut is already or
2ea20 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c dered */. doubl
2ea30 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b e estimatedCost;
2ea40 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 /* Estimat
2ea50 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 ed cost of using
2ea60 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d this index */.}
2ea70 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ;.#define SQLITE
2ea80 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
2ea90 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e T_EQ 2.#defin
2eaa0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
2eab0 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 ONSTRAINT_GT
2eac0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
2ead0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
2eae0 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e T_LE 8.#defin
2eaf0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
2eb00 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 ONSTRAINT_LT
2eb10 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 16.#define SQLIT
2eb20 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
2eb30 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 NT_GE 32.#def
2eb40 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
2eb50 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 _CONSTRAINT_MATC
2eb60 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 H 64../*.** CAPI
2eb70 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 3REF: Register A
2eb80 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 Virtual Table I
2eb90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 mplementation {H
2eba0 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18200} <S20400>.
2ebb0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
2ebc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
2ebd0 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 ne is used to re
2ebe0 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64 gister a new mod
2ebf0 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 0a ule name with a.
2ec00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
2ec10 6e 65 63 74 69 6f 6e 5d 2e 20 20 4d 6f 64 75 6c nection]. Modul
2ec20 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 e names must be
2ec30 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 registered befor
2ec40 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 6e 65 e.** creating ne
2ec50 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 w virtual tables
2ec60 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 on the module,
2ec70 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 0a or before using.
2ec80 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 76 ** preexisting v
2ec90 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 66 irtual tables of
2eca0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a the module..**.
2ecb0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
2ecc0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 e is experimenta
2ecd0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 l and is subject
2ece0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a to change or.**
2ecf0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 removal in futu
2ed00 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
2ed10 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 QLite..*/.SQLITE
2ed20 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
2ed30 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
2ed40 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 _module(. sqlit
2ed50 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2ed60 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 /* SQLite
2ed70 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 connection to re
2ed80 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 gister module wi
2ed90 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 th */. const ch
2eda0 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 ar *zName,
2edb0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
2edc0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f e module */. co
2edd0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 nst sqlite3_modu
2ede0 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 le *, /* Meth
2edf0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 ods for the modu
2ee00 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 le */. void *
2ee10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ee20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 /* Client dat
2ee30 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 a for xCreate/xC
2ee40 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a onnect */.);../*
2ee50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
2ee60 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c gister A Virtual
2ee70 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 Table Implement
2ee80 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c ation {H18210} <
2ee90 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20400>.** EXPER
2eea0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
2eeb0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 is routine is id
2eec0 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b entical to the [
2eed0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
2eee0 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 20 odule()] method
2eef0 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 above,.** except
2ef00 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 that it allows
2ef10 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e a destructor fun
2ef20 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 ction to be spec
2ef30 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 ified. It is.**
2ef40 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 even more experi
2ef50 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20 mental than the
2ef60 72 65 73 74 20 6f 66 20 74 68 65 20 76 69 72 74 rest of the virt
2ef70 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a ual tables API..
2ef80 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
2ef90 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
2efa0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
2efb0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
2efc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
2efd0 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e /* SQLite conn
2efe0 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 ection to regist
2eff0 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a er module with *
2f000 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2f010 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f zName, /
2f020 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f * Name of the mo
2f030 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 dule */. const
2f040 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a sqlite3_module *
2f050 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 , /* Methods
2f060 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a for the module *
2f070 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 /. void *,
2f080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2f090 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f * Client data fo
2f0a0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 r xCreate/xConne
2f0b0 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 ct */. void(*xD
2f0c0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 estroy)(void*)
2f0d0 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 /* Module des
2f0e0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e tructor function
2f0f0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
2f100 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
2f110 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f Table Instance O
2f120 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c bject {H18010} <
2f130 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20400>.** KEYWO
2f140 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 RDS: sqlite3_vta
2f150 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 b.** EXPERIMENTA
2f160 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f L.**.** Every mo
2f170 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 dule implementat
2f180 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c ion uses a subcl
2f190 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f ass of the follo
2f1a0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a wing structure.*
2f1b0 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 * to describe a
2f1c0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 particular insta
2f1d0 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c nce of the modul
2f1e0 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 e. Each subclas
2f1f0 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 s will.** be tai
2f200 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 lored to the spe
2f210 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 cific needs of t
2f220 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d he module implem
2f230 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 entation..** The
2f240 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 purpose of this
2f250 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 superclass is t
2f260 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e o define certain
2f270 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 fields that are
2f280 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c .** common to al
2f290 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 l module impleme
2f2a0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 ntations..**.**
2f2b0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d Virtual tables m
2f2c0 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 ethods can set a
2f2d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
2f2e0 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a by assigning a.*
2f2f0 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 * string obtaine
2f300 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2f310 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 mprintf()] to zE
2f320 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 rrMsg. The meth
2f330 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b od should.** tak
2f340 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 e care that any
2f350 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 prior string is
2f360 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 freed by a call
2f370 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 to [sqlite3_free
2f380 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 ()].** prior to
2f390 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 assigning a new
2f3a0 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 string to zErrMs
2f3b0 67 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72 g. After the er
2f3c0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 ror message.** i
2f3d0 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 s delivered up t
2f3e0 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 o the client app
2f3f0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 lication, the st
2f400 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 ring will be aut
2f410 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 omatically.** fr
2f420 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 eed by sqlite3_f
2f430 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 ree() and the zE
2f440 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c rrMsg field will
2f450 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 be zeroed. Not
2f460 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65 e.** that sqlite
2f470 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
2f480 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 sqlite3_free() a
2f490 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a re used on the z
2f4a0 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 ErrMsg field.**
2f4b0 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 since virtual ta
2f4c0 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c bles are commonl
2f4d0 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e y implemented in
2f4e0 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 loadable extens
2f4f0 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f ions which.** do
2f500 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 not have access
2f510 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e to sqlite3MPrin
2f520 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46 tf() or sqlite3F
2f530 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ree()..**.** Thi
2f540 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 s interface is e
2f550 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
2f560 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 is subject to ch
2f570 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 ange or.** remov
2f580 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c al in future rel
2f590 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
2f5a0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
2f5b0 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 e3_vtab {. cons
2f5c0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
2f5d0 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 *pModule; /* T
2f5e0 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 he module for th
2f5f0 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 is virtual table
2f600 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 */. int nRef;
2f610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2f620 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e /* Used in
2f630 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 ternally */. ch
2f640 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 ar *zErrMsg;
2f650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2f660 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 Error message f
2f670 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 rom sqlite3_mpri
2f680 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 ntf() */. /* Vi
2f690 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c rtual table impl
2f6a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
2f6b0 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 typically add a
2f6c0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
2f6d0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
2f6e0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
2f6f0 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a Table Cursor Obj
2f700 65 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 ect {H18020} <S
2f710 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 20400>.** KEYWOR
2f720 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 DS: sqlite3_vtab
2f730 5f 63 75 72 73 6f 72 0a 2a 2a 20 45 58 50 45 52 _cursor.** EXPER
2f740 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 IMENTAL.**.** Ev
2f750 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 ery module imple
2f760 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 mentation uses a
2f770 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 subclass of the
2f780 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 following struc
2f790 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 ture.** to descr
2f7a0 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 ibe cursors that
2f7b0 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 point into the
2f7c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e virtual table an
2f7d0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f d are used.** to
2f7e0 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 loop through th
2f7f0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e e virtual table.
2f800 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 Cursors are cr
2f810 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a eated using the.
2f820 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 ** xOpen method
2f830 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 of the module.
2f840 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c Each module impl
2f850 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 ementation will
2f860 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f define.** the co
2f870 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f ntent of a curso
2f880 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 r structure to s
2f890 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 uit its own need
2f8a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 s..**.** This su
2f8b0 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 perclass exists
2f8c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 in order to defi
2f8d0 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 ne fields of the
2f8e0 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 cursor that.**
2f8f0 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c are common to al
2f900 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e l implementation
2f910 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e s..**.** This in
2f920 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 terface is exper
2f930 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 imental and is s
2f940 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
2f950 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 or.** removal i
2f960 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
2f970 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a s of SQLite..*/.
2f980 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2f990 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 tab_cursor {. s
2f9a0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
2f9b0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 ab; /* Virt
2f9c0 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 ual table of thi
2f9d0 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a s cursor */. /*
2f9e0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 Virtual table i
2f9f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
2fa00 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 ill typically ad
2fa10 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 d additional fie
2fa20 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a lds */.};../*.**
2fa30 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
2fa40 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 re The Schema Of
2fa50 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 A Virtual Table
2fa60 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30 {H18280} <S2040
2fa70 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
2fa80 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 AL.**.** The xCr
2fa90 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 eate and xConnec
2faa0 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d t methods of a m
2fab0 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f odule use the fo
2fac0 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 llowing API.** t
2fad0 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f o declare the fo
2fae0 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 rmat (the names
2faf0 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 and datatypes of
2fb00 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 the columns) of
2fb10 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 .** the virtual
2fb20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c tables they impl
2fb30 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ement..**.** Thi
2fb40 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 s interface is e
2fb50 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
2fb60 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 is subject to ch
2fb70 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 ange or.** remov
2fb80 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c al in future rel
2fb90 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
2fba0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 .*/.SQLITE_EXPER
2fbb0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
2fbc0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 te3_declare_vtab
2fbd0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 (sqlite3*, const
2fbe0 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 char *zCreateTa
2fbf0 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ble);../*.** CAP
2fc00 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 I3REF: Overload
2fc10 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 A Function For A
2fc20 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b Virtual Table {
2fc30 48 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e H18300} <S20400>
2fc40 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
2fc50 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 .**.** Virtual t
2fc60 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 ables can provid
2fc70 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d e alternative im
2fc80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
2fc90 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 functions.** us
2fca0 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e ing the xFindFun
2fcb0 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 ction method. B
2fcc0 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f ut global versio
2fcd0 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 ns of those func
2fce0 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 tions.** must ex
2fcf0 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ist in order to
2fd00 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a be overloaded..*
2fd10 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 *.** This API ma
2fd20 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 kes sure a globa
2fd30 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 l version of a f
2fd40 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 unction with a p
2fd50 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d articular.** nam
2fd60 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 e and number of
2fd70 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 parameters exist
2fd80 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 s. If no such f
2fd90 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a unction exists.*
2fda0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 * before this AP
2fdb0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e I is called, a n
2fdc0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 ew function is c
2fdd0 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 reated. The imp
2fde0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f lementation.** o
2fdf0 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 f the new functi
2fe00 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 on always causes
2fe10 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f an exception to
2fe20 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a be thrown. So.
2fe30 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 ** the new funct
2fe40 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 ion is not good
2fe50 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 for anything by
2fe60 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c itself. Its onl
2fe70 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 y.** purpose is
2fe80 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c to be a placehol
2fe90 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 der function tha
2fea0 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 t can be overloa
2feb0 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 ded.** by virtua
2fec0 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 l tables..**.**
2fed0 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 This API should
2fee0 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 be considered pa
2fef0 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 rt of the virtua
2ff00 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 l table interfac
2ff10 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 e,.** which is e
2ff20 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
2ff30 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
2ff40 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 e..*/.SQLITE_EXP
2ff50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 ERIMENTAL int sq
2ff60 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 lite3_overload_f
2ff70 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a unction(sqlite3*
2ff80 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 , const char *zF
2ff90 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 uncName, int nAr
2ffa0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 g);../*.** The i
2ffb0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
2ffc0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
2ffd0 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 chanism defined
2ffe0 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a above (back up.*
2fff0 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 * to a comment r
30000 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 emarkably simila
30010 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 r to this one) i
30020 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 s currently cons
30030 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 idered.** to be
30040 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 experimental. T
30050 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 he interface mig
30060 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 ht change in inc
30070 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a ompatible ways..
30080 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 ** If this is a
30090 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c problem for you,
300a0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 do not use the
300b0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 interface at thi
300c0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 s time..**.** Wh
300d0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 en the virtual-t
300e0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 able mechanism s
300f0 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 tabilizes, we wi
30100 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a ll declare the.*
30110 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 * interface fixe
30120 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e d, support it in
30130 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 definitely, and
30140 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d remove this comm
30150 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 ent..**.****** E
30160 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 XPERIMENTAL - su
30170 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
30180 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a without notice *
30190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f *************.*/
301a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
301b0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e : A Handle To An
301c0 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 Open BLOB {H178
301d0 30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 00} <S30230>.**
301e0 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 KEYWORDS: {BLOB
301f0 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 handle} {BLOB ha
30200 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ndles}.**.** An
30210 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
30220 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
30230 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 ts an open BLOB
30240 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c on which.** [sql
30250 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c ite3_blob_open |
30260 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f incremental BLO
30270 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 B I/O] can be pe
30280 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 rformed..** Obje
30290 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 cts of this type
302a0 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 are created by
302b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
302c0 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 en()].** and des
302d0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
302e0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
302f0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
30300 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 3_blob_read()] a
30310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 nd [sqlite3_blob
30320 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 _write()] interf
30330 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 aces.** can be u
30340 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 sed to read or w
30350 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 rite small subse
30360 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c ctions of the BL
30370 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 OB..** The [sqli
30380 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 te3_blob_bytes()
30390 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
303a0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 rns the size of
303b0 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 the BLOB in byte
303c0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
303d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f ruct sqlite3_blo
303e0 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a b sqlite3_blob;.
303f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30400 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 Open A BLOB For
30410 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f Incremental I/O
30420 20 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33 {H17810} <S3023
30430 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
30440 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 terfaces opens a
30450 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 [BLOB handle |
30460 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 handle] to the B
30470 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 LOB located.** i
30480 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 n row iRow, colu
30490 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c mn zColumn, tabl
304a0 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 e zTable in data
304b0 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 base zDb;.** in
304c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
304d0 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 same BLOB that
304e0 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 would be selecte
304f0 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 d by:.**.** <pre
30500 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 >.** SELECT
30510 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 zColumn FROM zDb
30520 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 .zTable WHERE [r
30530 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a owid] = iRow;.**
30540 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a </pre> {END}.**
30550 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 .** If the flags
30560 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f parameter is no
30570 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 74 68 65 20 n-zero, the the
30580 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 BLOB is opened f
30590 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 or read.** and w
305a0 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 rite access. If
305b0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 it is zero, the
305c0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 BLOB is opened f
305d0 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a or read access..
305e0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
305f0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
30600 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c e is not the fil
30610 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 ename that conta
30620 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ins.** the datab
30630 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74 ase but rather t
30640 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 he symbolic name
30650 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
30660 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 that.** is assi
30670 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 gned when the da
30680 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 tabase is connec
30690 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 ted using [ATTAC
306a0 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d H]..** For the m
306b0 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
306c0 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 e, the database
306d0 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a name is "main"..
306e0 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 61 62 6c ** For TEMP tabl
306f0 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 es, the database
30700 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e name is "temp".
30710 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 .**.** On succes
30720 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 s, [SQLITE_OK] i
30730 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 s returned and t
30740 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e he new [BLOB han
30750 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a dle] is written.
30760 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f ** to *ppBlob. O
30770 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
30780 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
30790 72 6e 65 64 20 61 6e 64 20 61 6e 79 20 76 61 6c rned and any val
307a0 75 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f ue written.** to
307b0 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 *ppBlob should
307c0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 not be used by t
307d0 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 he caller..** Th
307e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 is function sets
307f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
30800 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 onnection] error
30810 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 code and messag
30820 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 e.** accessible
30830 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 via [sqlite3_err
30840 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c code()] and [sql
30850 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a ite3_errmsg()]..
30860 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f 77 **.** If the row
30870 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e that a BLOB han
30880 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 dle points to is
30890 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a modified by an.
308a0 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 ** [UPDATE], [DE
308b0 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e LETE], or by [ON
308c0 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d CONFLICT] side-
308d0 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 effects.** then
308e0 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 the BLOB handle
308f0 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 is marked as "ex
30900 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 pired"..** This
30910 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 is true if any c
30920 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 olumn of the row
30930 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 is changed, eve
30940 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 n a column.** ot
30950 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 her than the one
30960 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 the BLOB handle
30970 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 is open on..**
30980 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 Calls to [sqlite
30990 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 3_blob_read()] a
309a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 nd [sqlite3_blob
309b0 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a _write()] for.**
309c0 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20 a expired BLOB
309d0 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68 handle fail with
309e0 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20 an return code
309f0 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 of [SQLITE_ABORT
30a00 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 72 ]..** Changes wr
30a10 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f itten into a BLO
30a20 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 B prior to the B
30a30 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 LOB expiring are
30a40 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b not.** rollback
30a50 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69 by the expirati
30a60 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 on of the BLOB.
30a70 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 Such changes wi
30a80 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a ll eventually.**
30a90 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 commit if the t
30aa0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 ransaction conti
30ab0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 nues to completi
30ac0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 on..**.** Requir
30ad0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 ements:.** [H178
30ae0 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b 48 31 13] [H17814] [H1
30af0 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b 7816] [H17819] [
30b00 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32 34 5d H17821] [H17824]
30b10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
30b20 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c blob_open(. sql
30b30 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 ite3*,. const c
30b40 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 har *zDb,. cons
30b50 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a t char *zTable,.
30b60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
30b70 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 olumn,. sqlite3
30b80 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 _int64 iRow,. i
30b90 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 nt flags,. sqli
30ba0 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f te3_blob **ppBlo
30bb0 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 b.);../*.** CAPI
30bc0 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 3REF: Close A BL
30bd0 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 OB Handle {H1783
30be0 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 0} <S30230>.**.*
30bf0 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e * Closes an open
30c00 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a [BLOB handle]..
30c10 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 **.** Closing a
30c20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 BLOB shall cause
30c30 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 the current tra
30c40 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d nsaction to comm
30c50 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 it.** if there a
30c60 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 re no other BLOB
30c70 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 s, no pending pr
30c80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
30c90 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 s, and the.** da
30ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30cb0 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d n is in [autocom
30cc0 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 mit mode]..** If
30cd0 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 any writes were
30ce0 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f made to the BLO
30cf0 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 B, they might be
30d00 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a held in cache.*
30d10 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 * until the clos
30d20 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 e operation if t
30d30 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45 hey will fit. {E
30d40 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e ND}.**.** Closin
30d50 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e g the BLOB often
30d60 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e forces the chan
30d70 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 ges.** out to di
30d80 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 sk and so if any
30d90 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 I/O errors occu
30da0 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b r, they will lik
30db0 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 ely occur.** at
30dc0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 the time when th
30dd0 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 e BLOB is closed
30de0 2e 20 20 7b 48 31 37 38 33 33 7d 20 41 6e 79 20 . {H17833} Any
30df0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
30e00 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 r during.** clos
30e10 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 ing are reported
30e20 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 as a non-zero r
30e30 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a eturn value..**.
30e40 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 ** The BLOB is c
30e50 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f losed unconditio
30e60 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 nally. Even if
30e70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
30e80 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 urns.** an error
30e90 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 code, the BLOB
30ea0 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e is still closed.
30eb0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
30ec0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d nts:.** [H17833]
30ed0 20 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38 33 [H17836] [H1783
30ee0 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 9].*/.int sqlite
30ef0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 3_blob_close(sql
30f00 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f ite3_blob *);../
30f10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
30f20 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f eturn The Size O
30f30 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b f An Open BLOB {
30f40 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e H17840} <S30230>
30f50 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 .**.** Returns t
30f60 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 he size in bytes
30f70 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 of the BLOB acc
30f80 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 essible via the
30f90 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20 68 open.** []BLOB h
30fa0 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e andle] in its on
30fb0 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a ly argument..**.
30fc0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
30fd0 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a .** [H17843].*/.
30fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
30ff0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 _bytes(sqlite3_b
31000 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 lob *);../*.** C
31010 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 API3REF: Read Da
31020 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 ta From A BLOB I
31030 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 ncrementally {H1
31040 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 7850} <S30230>.*
31050 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
31060 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 on is used to re
31070 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 ad data from an
31080 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c open [BLOB handl
31090 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c e] into a.** cal
310a0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 ler-supplied buf
310b0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 fer. N bytes of
310c0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 data are copied
310d0 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a into buffer Z.**
310e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 from the open B
310f0 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 LOB, starting at
31100 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e offset iOffset.
31110 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 .**.** If offset
31120 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 iOffset is less
31130 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 than N bytes fr
31140 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 om the end of th
31150 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 e BLOB,.** [SQLI
31160 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 TE_ERROR] is ret
31170 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 urned and no dat
31180 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e a is read. If N
31190 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a or iOffset is.*
311a0 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f * less than zero
311b0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
311c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
311d0 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 no data is read
311e0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d ..**.** An attem
311f0 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 pt to read from
31200 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 an expired [BLOB
31210 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 handle] fails w
31220 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 ith an.** error
31230 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f code of [SQLITE_
31240 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e ABORT]..**.** On
31250 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 success, SQLITE
31260 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
31270 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 .** Otherwise, a
31280 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f n [error code] o
31290 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 r an [extended e
312a0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
312b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 turned..**.** Re
312c0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
312d0 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 5d H17853] [H17856]
312e0 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 36 [H17859] [H1786
312f0 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 2] [H17863] [H17
31300 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 865] [H17868].*/
31310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
31320 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 b_read(sqlite3_b
31330 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 lob *, void *Z,
31340 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 int N, int iOffs
31350 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 et);../*.** CAPI
31360 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 3REF: Write Data
31370 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 Into A BLOB Inc
31380 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 rementally {H178
31390 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 70} <S30230>.**.
313a0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
313b0 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 is used to writ
313c0 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f e data into an o
313d0 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 pen [BLOB handle
313e0 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c ] from a.** call
313f0 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 er-supplied buff
31400 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 er. N bytes of d
31410 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 ata are copied f
31420 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a rom the buffer Z
31430 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 .** into the ope
31440 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 n BLOB, starting
31450 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 at offset iOffs
31460 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 et..**.** If the
31470 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 [BLOB handle] p
31480 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
31490 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 st argument was
314a0 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a not opened for.*
314b0 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 * writing (the f
314c0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
314d0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f o [sqlite3_blob_
314e0 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f open()] was zero
314f0 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 ),.** this funct
31500 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ion returns [SQL
31510 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a ITE_READONLY]..*
31520 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
31530 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 on may only modi
31540 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 fy the contents
31550 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 of the BLOB; it
31560 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 is.** not possib
31570 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 le to increase t
31580 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f he size of a BLO
31590 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 B using this API
315a0 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 ..** If offset i
315b0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 Offset is less t
315c0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d han N bytes from
315d0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
315e0 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 BLOB,.** [SQLITE
315f0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 _ERROR] is retur
31600 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 ned and no data
31610 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20 is written. If
31620 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 N is.** less tha
31630 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 n zero [SQLITE_E
31640 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
31650 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
31660 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 written..**.**
31670 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 An attempt to wr
31680 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 ite to an expire
31690 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 d [BLOB handle]
316a0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a fails with an.**
316b0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b error code of [
316c0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 SQLITE_ABORT].
316d0 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c Writes to the BL
316e0 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 OB that occurred
316f0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
31700 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 BLOB handle] exp
31710 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c ired are not rol
31720 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a led back by the.
31730 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 ** expiration of
31740 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f the handle, tho
31750 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
31760 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 ose changes migh
31770 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f t.** have been o
31780 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 verwritten by th
31790 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 e statement that
317a0 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f expired the BLO
317b0 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 B handle.** or b
317c0 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 y other independ
317d0 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a ent statements..
317e0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
317f0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 , SQLITE_OK is r
31800 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 eturned..** Othe
31810 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f rwise, an [erro
31820 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 r code] or an [e
31830 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
31840 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
31850 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
31860 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d nts:.** [H17873]
31870 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37 [H17874] [H1787
31880 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37 5] [H17876] [H17
31890 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48 877] [H17879] [H
318a0 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a 17882] [H17885].
318b0 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 ** [H17888].*/.i
318c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
318d0 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c write(sqlite3_bl
318e0 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ob *, const void
318f0 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 *z, int n, int
31900 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a iOffset);../*.**
31910 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 CAPI3REF: Virtu
31920 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f al File System O
31930 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20 bjects {H11200}
31940 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 <S20100>.**.** A
31950 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 virtual filesys
31960 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 tem (VFS) is an
31970 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
31980 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c ject.** that SQL
31990 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 ite uses to inte
319a0 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 ract.** with the
319b0 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
319c0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d ating system. M
319d0 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 ost SQLite build
319e0 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a s come with a.**
319f0 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 single default
31a00 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 VFS that is appr
31a10 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 opriate for the
31a20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a host computer..*
31a30 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 * New VFSes can
31a40 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e be registered an
31a50 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 d existing VFSes
31a60 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 can be unregist
31a70 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c ered..** The fol
31a80 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 lowing interface
31a90 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a s are provided..
31aa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
31ab0 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 3_vfs_find() int
31ac0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
31ad0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 pointer to a VF
31ae0 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 S given its name
31af0 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 ..** Names are c
31b00 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a ase sensitive..*
31b10 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f * Names are zero
31b20 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
31b30 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 8 strings..** If
31b40 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 there is no mat
31b50 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ch, a NULL point
31b60 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
31b70 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 ** If zVfsName i
31b80 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 s NULL then the
31b90 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 default VFS is r
31ba0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e eturned..**.** N
31bb0 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 ew VFSes are reg
31bc0 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c istered with sql
31bd0 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
31be0 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 r()..** Each new
31bf0 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 VFS becomes the
31c00 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 default VFS if
31c10 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 the makeDflt fla
31c20 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 g is set..** The
31c30 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 same VFS can be
31c40 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 registered mult
31c50 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f iple times witho
31c60 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f ut injury..** To
31c70 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e make an existin
31c80 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 g VFS into the d
31c90 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 efault VFS, regi
31ca0 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a ster it again.**
31cb0 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 with the makeDf
31cc0 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 lt flag set. If
31cd0 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 two different V
31ce0 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a FSes with the.**
31cf0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 same name are r
31d00 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 egistered, the b
31d10 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
31d20 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 ined. If a.** V
31d30 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64 FS is registered
31d40 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 with a name tha
31d50 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 t is NULL or an
31d60 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a empty string,.**
31d70 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
31d80 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
31d90 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 .**.** Unregiste
31da0 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 r a VFS with the
31db0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 sqlite3_vfs_unr
31dc0 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 egister() interf
31dd0 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 ace..** If the d
31de0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e efault VFS is un
31df0 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 registered, anot
31e00 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 her VFS is chose
31e10 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 n as.** the defa
31e20 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 ult. The choice
31e30 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 for the new VFS
31e40 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a is arbitrary..*
31e50 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
31e60 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b s:.** [H11203] [
31e70 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d H11206] [H11209]
31e80 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31 [H11212] [H1121
31e90 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 5] [H11218].*/.s
31ea0 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 qlite3_vfs *sqli
31eb0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e te3_vfs_find(con
31ec0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d st char *zVfsNam
31ed0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f e);.int sqlite3_
31ee0 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c vfs_register(sql
31ef0 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d ite3_vfs*, int m
31f00 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 akeDflt);.int sq
31f10 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
31f20 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 ster(sqlite3_vfs
31f30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
31f40 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 REF: Mutexes {H1
31f50 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 7000} <S20000>.*
31f60 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
31f70 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 core uses these
31f80 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 routines for thr
31f90 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 ead.** synchroni
31fa0 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 zation. Though t
31fb0 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 hey are intended
31fc0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a for internal.**
31fd0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 use by SQLite,
31fe0 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 code that links
31ff0 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 against SQLite i
32000 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 s.** permitted t
32010 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 o use any of the
32020 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
32030 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f ** The SQLite so
32040 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 urce code contai
32050 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c ns multiple impl
32060 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f ementations.** o
32070 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f f these mutex ro
32080 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 utines. An appr
32090 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e opriate implemen
320a0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c tation.** is sel
320b0 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 ected automatica
320c0 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 lly at compile-t
320d0 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 ime. The follow
320e0 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ing.** implement
320f0 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c ations are avail
32100 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 able in the SQLi
32110 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c te core:.**.** <
32120 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 ul>.** <li> SQ
32130 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a LITE_MUTEX_OS2.*
32140 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f * <li> SQLITE_
32150 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a MUTEX_PTHREAD.**
32160 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d <li> SQLITE_M
32170 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e UTEX_W32.** <li>
32180 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f SQLITE_MUTEX_
32190 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a NOOP.** </ul>.**
321a0 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d .** The SQLITE_M
321b0 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d UTEX_NOOP implem
321c0 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 entation is a se
321d0 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a t of routines.**
321e0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 that does no re
321f0 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 al locking and i
32200 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f s appropriate fo
32210 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 r use in.** a si
32220 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 ngle-threaded ap
32230 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 plication. The
32240 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 SQLITE_MUTEX_OS2
32250 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 ,.** SQLITE_MUTE
32260 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 X_PTHREAD, and S
32270 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 QLITE_MUTEX_W32
32280 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a implementations.
32290 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 ** are appropria
322a0 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 te for use on OS
322b0 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 /2, Unix, and Wi
322c0 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ndows..**.** If
322d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
322e0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 ed with the SQLI
322f0 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 TE_MUTEX_APPDEF
32300 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 preprocessor.**
32310 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 macro defined (w
32320 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 ith "-DSQLITE_MU
32330 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 TEX_APPDEF=1"),
32340 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a then no mutex.**
32350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
32360 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 is included with
32370 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e the library. In
32380 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a this case the.*
32390 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 * application mu
323a0 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 st supply a cust
323b0 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 om mutex impleme
323c0 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 ntation using th
323d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e.** [SQLITE_CON
323e0 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f FIG_MUTEX] optio
323f0 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 n of the sqlite3
32400 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 _config() functi
32410 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c on.** before cal
32420 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 ling sqlite3_ini
32430 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 tialize() or any
32440 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 other public sq
32450 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 lite3_.** functi
32460 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 on that calls sq
32470 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
32480 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 ()..**.** {H1701
32490 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 1} The sqlite3_m
324a0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 utex_alloc() rou
324b0 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 tine allocates a
324c0 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e new.** mutex an
324d0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
324e0 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 ter to it. {H170
324f0 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 12} If it return
32500 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d s NULL.** that m
32510 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 eans that a mute
32520 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 x could not be a
32530 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31 llocated. {H1701
32540 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 3} SQLite.** wil
32550 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 l unwind its sta
32560 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e ck and return an
32570 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d error. {H17014}
32580 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a The argument.**
32590 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
325a0 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 x_alloc() is one
325b0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
325c0 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a r constants:.**.
325d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
325e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
325f0 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ST.** <li> SQLI
32600 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
32610 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 VE.** <li> SQLI
32620 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
32630 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 MASTER.** <li>
32640 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
32650 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 TIC_MEM.** <li>
32660 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
32670 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 ATIC_MEM2.** <li
32680 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
32690 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c STATIC_PRNG.** <
326a0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
326b0 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 X_STATIC_LRU.**
326c0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
326d0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a EX_STATIC_LRU2.*
326e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 * </ul>.**.** {H
326f0 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 17015} The first
32700 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 two constants c
32710 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 ause sqlite3_mut
32720 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 ex_alloc() to cr
32730 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 eate.** a new mu
32740 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 tex. The new mu
32750 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 tex is recursive
32760 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 when SQLITE_MUT
32770 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 EX_RECURSIVE.**
32780 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 is used but not
32790 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 necessarily so w
327a0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 hen SQLITE_MUTEX
327b0 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b _FAST is used. {
327c0 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 END}.** The mute
327d0 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
327e0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
327f0 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 o make a distinc
32800 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 tion.** between
32810 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
32820 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 URSIVE and SQLIT
32830 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 E_MUTEX_FAST if
32840 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 it does.** not w
32850 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 ant to. {H17016
32860 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c } But SQLite wil
32870 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 l only request a
32880 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 recursive mutex
32890 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 in.** cases whe
328a0 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 re it really nee
328b0 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 ds one. {END} I
328c0 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 f a faster non-r
328d0 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a ecursive mutex.*
328e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
328f0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e is available on
32900 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f the host platfo
32910 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 rm, the mutex su
32920 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 bsystem.** might
32930 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d return such a m
32940 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 utex in response
32950 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 to SQLITE_MUTEX
32960 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 _FAST..**.** {H1
32970 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 7017} The other
32980 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 allowed paramete
32990 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 rs to sqlite3_mu
329a0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 tex_alloc() each
329b0 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 return.** a poi
329c0 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 nter to a static
329d0 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 preexisting mut
329e0 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 ex. {END} Four
329f0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 static mutexes a
32a00 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 re.** used by th
32a10 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f e current versio
32a20 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 n of SQLite. Fu
32a30 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
32a40 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 SQLite.** may a
32a50 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 dd additional st
32a60 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 atic mutexes. S
32a70 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 tatic mutexes ar
32a80 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a e for internal.*
32a90 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 * use by SQLite
32aa0 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 only. Applicati
32ab0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c ons that use SQL
32ac0 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 ite mutexes shou
32ad0 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 ld.** use only t
32ae0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
32af0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 es returned by S
32b00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
32b10 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 or.** SQLITE_MU
32b20 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a TEX_RECURSIVE..*
32b30 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f *.** {H17018} No
32b40 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f te that if one o
32b50 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 f the dynamic mu
32b60 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 tex parameters (
32b70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
32b80 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d T.** or SQLITE_M
32b90 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 UTEX_RECURSIVE)
32ba0 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c is used then sql
32bb0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
32bc0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ().** returns a
32bd0 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 different mutex
32be0 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 on every call.
32bf0 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 {H17034} But for
32c00 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d the static.** m
32c10 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 utex types, the
32c20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 same mutex is re
32c30 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 turned on every
32c40 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a call that has.**
32c50 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e the same type n
32c60 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 umber..**.** {H1
32c70 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 7019} The sqlite
32c80 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 3_mutex_free() r
32c90 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 outine deallocat
32ca0 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a es a previously.
32cb0 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e ** allocated dyn
32cc0 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 amic mutex. {H17
32cd0 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 020} SQLite is c
32ce0 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f areful to deallo
32cf0 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 cate every.** dy
32d00 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 namic mutex that
32d10 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b it allocates. {
32d20 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 A17021} The dyna
32d30 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 mic mutexes must
32d40 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 not be in.** us
32d50 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 e when they are
32d60 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 deallocated. {A1
32d70 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 7022} Attempting
32d80 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 to deallocate a
32d90 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 static.** mutex
32da0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
32db0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 fined behavior.
32dc0 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20 {H17023} SQLite
32dd0 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 never deallocate
32de0 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 s.** a static mu
32df0 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a tex. {END}.**.**
32e00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 The sqlite3_mut
32e10 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 ex_enter() and s
32e20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
32e30 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 () routines atte
32e40 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 mpt.** to enter
32e50 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34 a mutex. {H17024
32e60 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 } If another thr
32e70 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 ead is already w
32e80 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c ithin the mutex,
32e90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 .** sqlite3_mute
32ea0 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 x_enter() will b
32eb0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 lock and sqlite3
32ec0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c _mutex_try() wil
32ed0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 l return.** SQLI
32ee0 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35 TE_BUSY. {H17025
32ef0 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d } The sqlite3_m
32f00 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 utex_try() inter
32f10 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 face returns [SQ
32f20 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e LITE_OK].** upon
32f30 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 successful entr
32f40 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 y. {H17026} Mut
32f50 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 exes created usi
32f60 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 ng.** SQLITE_MUT
32f70 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e EX_RECURSIVE can
32f80 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 be entered mult
32f90 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 iple times by th
32fa0 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a e same thread..*
32fb0 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75 * {H17027} In su
32fc0 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a ch cases the,.**
32fd0 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 mutex must be e
32fe0 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e xited an equal n
32ff0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 umber of times b
33000 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 efore another th
33010 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 read.** can ente
33020 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20 r. {A17028} If
33030 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
33040 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 tries to enter a
33050 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 ny other.** kind
33060 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 of mutex more t
33070 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 han once, the be
33080 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
33090 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d ned..** {H17029}
330a0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
330b0 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 er exhibit.** su
330c0 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 ch behavior in i
330d0 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 ts own use of mu
330e0 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d texes..**.** Som
330f0 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 e systems (for e
33100 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 xample, Windows
33110 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 95) do not suppo
33120 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e rt the operation
33130 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 .** implemented
33140 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 by sqlite3_mutex
33150 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 _try(). On thos
33160 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 e systems, sqlit
33170 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a e3_mutex_try().*
33180 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 * will always re
33190 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 turn SQLITE_BUSY
331a0 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20 . {H17030} The
331b0 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 SQLite core only
331c0 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 ever uses.** sq
331d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
331e0 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 ) as an optimiza
331f0 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 tion so this is
33200 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 acceptable behav
33210 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 ior..**.** {H170
33220 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 31} The sqlite3_
33230 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f mutex_leave() ro
33240 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 utine exits a mu
33250 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 tex that was.**
33260 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 previously enter
33270 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 ed by the same t
33280 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d hread. {A17032}
33290 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a The behavior.**
332a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 is undefined if
332b0 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f the mutex is no
332c0 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 t currently ente
332d0 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 red by the.** ca
332e0 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 lling thread or
332f0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
33300 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 allocated. {H1
33310 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 7033} SQLite wil
33320 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 l.** never do ei
33330 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a ther. {END}.**.*
33340 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e * If the argumen
33350 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 t to sqlite3_mut
33360 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 ex_enter(), sqli
33370 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c te3_mutex_try(),
33380 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d or.** sqlite3_m
33390 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 utex_leave() is
333a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
333b0 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 then all three r
333c0 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 outines.** behav
333d0 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a e as no-ops..**.
333e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
333f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
33400 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
33410 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
33420 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 ]..*/.sqlite3_mu
33430 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 tex *sqlite3_mut
33440 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 ex_alloc(int);.v
33450 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 oid sqlite3_mute
33460 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d x_free(sqlite3_m
33470 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c utex*);.void sql
33480 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
33490 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
334a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 ;.int sqlite3_mu
334b0 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f tex_try(sqlite3_
334c0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 mutex*);.void sq
334d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
334e0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a e(sqlite3_mutex*
334f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
33500 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 EF: Mutex Method
33510 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 s Object {H17120
33520 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 } <S20130>.** EX
33530 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
33540 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
33550 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 this structure d
33560 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c efines the low-l
33570 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a evel routines.**
33580 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 used to allocat
33590 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 e and use mutexe
335a0 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 s..**.** Usually
335b0 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 , the default mu
335c0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
335d0 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 ons provided by
335e0 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 SQLite are.** su
335f0 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 fficient, howeve
33600 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 r the user has t
33610 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 he option of sub
33620 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 stituting a cust
33630 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 om.** implementa
33640 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c tion for special
33650 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 ized deployments
33660 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 or systems for
33670 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 which SQLite.**
33680 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 does not provide
33690 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
336a0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 ementation. In t
336b0 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 his case, the us
336c0 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e er.** creates an
336d0 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 d populates an i
336e0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
336f0 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 structure to pas
33700 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f s.** to sqlite3_
33710 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 config() along w
33720 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
33730 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 CONFIG_MUTEX] op
33740 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f tion..** Additio
33750 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e nally, an instan
33760 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 ce of this struc
33770 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
33780 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 as an.** output
33790 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 variable when q
337a0 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 uerying the syst
337b0 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 em for the curre
337c0 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c nt mutex.** impl
337d0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e ementation, usin
337e0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
337f0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f NFIG_GETMUTEX] o
33800 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ption..**.** The
33810 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 xMutexInit meth
33820 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 od defined by th
33830 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 is structure is
33840 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 invoked as.** pa
33850 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 rt of system ini
33860 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 tialization by t
33870 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
33880 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e alize() function
33890 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 ..** {H17001} Th
338a0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 e xMutexInit rou
338b0 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 tine shall be ca
338c0 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f lled by SQLite o
338d0 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 nce for each.**
338e0 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 effective call t
338f0 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 o [sqlite3_initi
33900 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 alize()]..**.**
33910 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 The xMutexEnd me
33920 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 thod defined by
33930 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 this structure i
33940 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 s invoked as.**
33950 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 part of system s
33960 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 hutdown by the s
33970 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
33980 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a ) function. The.
33990 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
339a0 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 n of this method
339b0 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 is expected to
339c0 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 release all outs
339d0 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 tanding.** resou
339e0 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 rces obtained by
339f0 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f the mutex metho
33a00 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ds implementatio
33a10 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a n, especially.**
33a20 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 those obtained
33a30 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 by the xMutexIni
33a40 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 t method. {H1700
33a50 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 3} The xMutexEnd
33a60 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
33a70 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 shall be invoked
33a80 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 once for each c
33a90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
33aa0 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a shutdown()]..**.
33ab0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 ** The remaining
33ac0 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 seven methods d
33ad0 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 efined by this s
33ae0 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 tructure (xMutex
33af0 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 Alloc,.** xMutex
33b00 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 Free, xMutexEnte
33b10 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d r, xMutexTry, xM
33b20 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 utexLeave, xMute
33b30 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 xHeld and.** xMu
33b40 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c texNotheld) impl
33b50 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 ement the follow
33b60 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 ing interfaces (
33b70 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a respectively):.*
33b80 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c *.** <ul>.** <
33b90 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
33ba0 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c tex_alloc()] </l
33bb0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
33bc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 qlite3_mutex_fre
33bd0 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 e()] </li>.**
33be0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
33bf0 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f utex_enter()] </
33c00 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
33c10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
33c20 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 y()] </li>.**
33c30 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
33c40 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f utex_leave()] </
33c50 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
33c60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
33c70 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 ld()] </li>.**
33c80 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
33c90 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d mutex_notheld()]
33ca0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a </li>.** </ul>.
33cb0 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 **.** The only d
33cc0 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 ifference is tha
33cd0 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c t the public sql
33ce0 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f ite3_XXX functio
33cf0 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a ns enumerated.**
33d00 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 above silently
33d10 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 ignore any invoc
33d20 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 ations that pass
33d30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
33d40 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
33d50 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 valid mutex hand
33d60 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e le. The implemen
33d70 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d tations of the m
33d80 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a ethods defined.*
33d90 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 * by this struct
33da0 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 ure are not requ
33db0 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 ired to handle t
33dc0 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 his case, the re
33dd0 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 sults.** of pass
33de0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ing a NULL point
33df0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 er instead of a
33e00 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 valid mutex hand
33e10 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 le are undefined
33e20 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 .** (i.e. it is
33e30 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 acceptable to pr
33e40 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 ovide an impleme
33e50 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 ntation that seg
33e60 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 faults if.** it
33e70 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c is passed a NULL
33e80 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 pointer)..*/.ty
33e90 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
33ea0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
33eb0 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ds sqlite3_mutex
33ec0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
33ed0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
33ee0 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 ethods {. int (
33ef0 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 *xMutexInit)(voi
33f00 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 d);. int (*xMut
33f10 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 exEnd)(void);.
33f20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 sqlite3_mutex *(
33f30 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e *xMutexAlloc)(in
33f40 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 t);. void (*xMu
33f50 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 texFree)(sqlite3
33f60 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 _mutex *);. voi
33f70 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 d (*xMutexEnter)
33f80 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
33f90 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
33fa0 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 xTry)(sqlite3_mu
33fb0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 tex *);. void (
33fc0 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 *xMutexLeave)(sq
33fd0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
33fe0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 int (*xMutexHe
33ff0 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ld)(sqlite3_mute
34000 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d x *);. int (*xM
34010 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c utexNotheld)(sql
34020 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d ite3_mutex *);.}
34030 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
34040 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 F: Mutex Verific
34050 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b ation Routines {
34060 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e H17080} <S20130>
34070 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30800>.**.**
34080 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
34090 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c x_held() and sql
340a0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
340b0 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a ld() routines.**
340c0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
340d0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 r use inside ass
340e0 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 ert() statements
340f0 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 . {H17081} The S
34100 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 QLite core.** ne
34110 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 ver uses these r
34120 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 outines except i
34130 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 nside an assert(
34140 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f ) and applicatio
34150 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 ns.** are advise
34160 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 d to follow the
34170 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 lead of the core
34180 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 . {H17082} The
34190 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f core only.** pro
341a0 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 vides implementa
341b0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 tions for these
341c0 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 routines when it
341d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 is compiled.**
341e0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
341f0 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 DEBUG flag. {A1
34200 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 7087} External m
34210 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 utex implementat
34220 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 ions.** are only
34230 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f required to pro
34240 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 vide these routi
34250 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 nes if SQLITE_DE
34260 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 BUG is.** define
34270 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 d and if NDEBUG
34280 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a is not defined..
34290 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 **.** {H17083} T
342a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 hese routines sh
342b0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 ould return true
342c0 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e if the mutex in
342d0 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a their argument.
342e0 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f ** is held or no
342f0 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 t held, respecti
34300 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c vely, by the cal
34310 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a ling thread..**.
34320 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 ** {X17084} The
34330 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
34340 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 s not required t
34350 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 o provided versi
34360 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ons of these.**
34370 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 routines that ac
34380 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 tually work. If
34390 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
343a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 on does not prov
343b0 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 ide working.** v
343c0 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 ersions of these
343d0 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 routines, it sh
343e0 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 ould at least pr
343f0 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74 ovide stubs that
34400 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 always.** retur
34410 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f n true so that o
34420 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 ne does not get
34430 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 spurious asserti
34440 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a on failures..**.
34450 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 ** {H17085} If t
34460 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 he argument to s
34470 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
34480 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f d() is a NULL po
34490 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 inter then.** th
344a0 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 e routine should
344b0 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 return 1. {END
344c0 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 } This seems cou
344d0 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 nter-intuitive s
344e0 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 ince.** clearly
344f0 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 the mutex cannot
34500 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 be held if it d
34510 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 oes not exist.
34520 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 But the.** the r
34530 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 eason the mutex
34540 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 does not exist i
34550 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 s because the bu
34560 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 ild is not.** us
34570 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e ing mutexes. An
34580 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 d we do not want
34590 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f the assert() co
345a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 ntaining the.**
345b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
345c0 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 mutex_held() to
345d0 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a fail, so a non-z
345e0 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a ero return is.**
345f0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 the appropriate
34600 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b thing to do. {
34610 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 H17086} The sqli
34620 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c te3_mutex_nothel
34630 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 d().** interface
34640 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 should also ret
34650 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e urn 1 when given
34660 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
34670 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
34680 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 mutex_held(sqlit
34690 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 e3_mutex*);.int
346a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
346b0 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 theld(sqlite3_mu
346c0 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tex*);../*.** CA
346d0 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 PI3REF: Mutex Ty
346e0 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 pes {H17001} <H1
346f0 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7000>.**.** The
34700 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 [sqlite3_mutex_a
34710 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 lloc()] interfac
34720 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 e takes a single
34730 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 argument.** whi
34740 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 ch is one of the
34750 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
34760 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ants..**.** The
34770 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 set of static mu
34780 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 texes may change
34790 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 from one SQLite
347a0 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a release to the.
347b0 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 ** next. Applic
347c0 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 ations that over
347d0 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ride the built-i
347e0 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 n mutex logic mu
347f0 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 st be.** prepare
34800 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 d to accommodate
34810 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 additional stat
34820 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 ic mutexes..*/.#
34830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
34840 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 TEX_FAST
34850 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
34860 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
34870 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 RSIVE 1.#
34880 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
34890 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
348a0 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 R 2.#define S
348b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
348c0 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 IC_MEM 3
348d0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f /* sqlite3_mallo
348e0 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 c() */.#define S
348f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
34900 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 IC_MEM2 4
34910 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 /* NOT USED */.#
34920 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
34930 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 TEX_STATIC_OPEN
34940 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 4 /* sqlit
34950 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f e3BtreeOpen() */
34960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
34970 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e MUTEX_STATIC_PRN
34980 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c G 5 /* sql
34990 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f ite3_random() */
349a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
349b0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 MUTEX_STATIC_LRU
349c0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 6 /* lru
349d0 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 page list */.#d
349e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
349f0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 EX_STATIC_LRU2
34a00 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 7 /* lru pa
34a10 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a ge list */../*.*
34a20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 * CAPI3REF: Retr
34a30 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 ieve the mutex f
34a40 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f or a database co
34a50 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 nnection {H17002
34a60 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a } <H17000>.**.**
34a70 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
34a80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
34a90 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d r the [sqlite3_m
34aa0 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 utex] object tha
34ab0 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 t .** serializes
34ac0 20 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b access to the [
34ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
34ae0 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 ion] given in th
34af0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 e argument.** wh
34b00 65 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e en the [threadin
34b10 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 g mode] is Seria
34b20 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 lized..** If the
34b30 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
34b40 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 ] is Single-thre
34b50 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 ad or Multi-thre
34b60 61 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 ad then this.**
34b70 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
34b80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
34b90 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 */.sqlite3_mutex
34ba0 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 *sqlite3_db_mut
34bb0 65 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f ex(sqlite3*);../
34bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
34bd0 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c ow-Level Control
34be0 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c Of Database Fil
34bf0 65 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 es {H11300} <S30
34c00 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 800>.**.** {H113
34c10 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 01} The [sqlite3
34c20 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
34c30 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 interface makes
34c40 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 a direct call t
34c50 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f o the.** xFileCo
34c60 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 ntrol method for
34c70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
34c80 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
34c90 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
34ca0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 ith a particular
34cb0 20 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 database identi
34cc0 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f fied by the seco
34cd0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 nd argument. {H1
34ce0 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 1302} The.** nam
34cf0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
34d00 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 e is the name as
34d10 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 signed to the da
34d20 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a tabase by the.**
34d30 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 <a href="lang_a
34d40 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 ttach.html">ATTA
34d50 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 CH</a> SQL comma
34d60 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 nd that opened t
34d70 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 he.** database.
34d80 7b 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 {H11303} To cont
34d90 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 rol the main dat
34da0 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 abase file, use
34db0 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a the name "main".
34dc0 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 ** or a NULL poi
34dd0 6e 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 nter. {H11304} T
34de0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 he third and fou
34df0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 rth parameters t
34e00 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a o this routine.*
34e10 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72 * are passed dir
34e20 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f ectly through to
34e30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
34e40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 third parameters
34e50 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 of.** the xFile
34e60 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 Control method.
34e70 20 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 {H11305} The re
34e80 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
34e90 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a e xFileControl.*
34ea0 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 * method becomes
34eb0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
34ec0 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e e of this routin
34ed0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 e..**.** {H11306
34ee0 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 } If the second
34ef0 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 parameter (zDbNa
34f00 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 me) does not mat
34f10 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 ch the name of a
34f20 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 ny.** open datab
34f30 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 ase file, then S
34f40 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 QLITE_ERROR is r
34f50 65 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 eturned. {H11307
34f60 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 } This error.**
34f70 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 code is not reme
34f80 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 mbered and will
34f90 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 not be recalled
34fa0 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 by [sqlite3_errc
34fb0 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 ode()].** or [sq
34fc0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
34fd0 20 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e {A11308} The un
34fe0 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f derlying xFileCo
34ff0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 ntrol method mig
35000 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 ht.** also retur
35010 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 n SQLITE_ERROR.
35020 20 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 {A11309} There
35030 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 is no way to dis
35040 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e tinguish between
35050 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 .** an incorrect
35060 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 zDbName and an
35070 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 SQLITE_ERROR ret
35080 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 urn from the und
35090 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 erlying.** xFile
350a0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 Control method.
350b0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 {END}.**.** See
350c0 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 also: [SQLITE_FC
350d0 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a NTL_LOCKSTATE].*
350e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 /.int sqlite3_fi
350f0 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 le_control(sqlit
35100 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 e3*, const char
35110 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 *zDbName, int op
35120 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
35130 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 CAPI3REF: Testi
35140 6e 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 ng Interface {H1
35150 31 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 1400} <S30800>.*
35160 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
35170 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 _test_control()
35180 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
35190 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e d to read out in
351a0 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 ternal.** state
351b0 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f of SQLite and to
351c0 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 inject faults i
351d0 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 nto SQLite for t
351e0 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 esting.** purpos
351f0 65 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 es. The first p
35200 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f arameter is an o
35210 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 peration code th
35220 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a at determines.**
35230 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 the number, mea
35240 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 ning, and operat
35250 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 ion of all subse
35260 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 quent parameters
35270 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
35280 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f erface is not fo
35290 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 r use by applica
352a0 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 tions. It exist
352b0 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 s solely.** for
352c0 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f verifying the co
352d0 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 rrect operation
352e0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
352f0 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e brary. Dependin
35300 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 g.** on how the
35310 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 SQLite library i
35320 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 s compiled, this
35330 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 interface might
35340 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a not exist..**.*
35350 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 * The details of
35360 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 the operation c
35370 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e odes, their mean
35380 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 ings, the parame
35390 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b ters.** they tak
353a0 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 e, and what they
353b0 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a do are all subj
353c0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 ect to change wi
353d0 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a thout notice..**
353e0 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 Unlike most of
353f0 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 the SQLite API,
35400 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 this function is
35410 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 not guaranteed
35420 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f to.** operate co
35430 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 nsistently from
35440 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 one release to t
35450 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 he next..*/.int
35460 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e sqlite3_test_con
35470 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e trol(int op, ...
35480 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
35490 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 EF: Testing Inte
354a0 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 rface Operation
354b0 43 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c Codes {H11410} <
354c0 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H11400>.**.** Th
354d0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
354e0 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 e the valid oper
354f0 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d ation code param
35500 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 eters used.** as
35510 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
35520 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
35530 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e test_control()].
35540 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 .**.** These par
35550 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 ameters and thei
35560 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 r meanings are s
35570 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
35580 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 .** without noti
35590 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 ce. These value
355a0 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e s are for testin
355b0 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e g purposes only.
355c0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
355d0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 should not use
355e0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 any of these par
355f0 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a ameters or the.*
35600 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f * [sqlite3_test_
35610 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 control()] inter
35620 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 face..*/.#define
35630 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
35640 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 _PRNG_SAVE
35650 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
35660 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
35670 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 TRL_PRNG_RESTORE
35680 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 6.#
35690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
356a0 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 STCTRL_PRNG_RESE
356b0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
356c0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
356d0 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 _TESTCTRL_BITVEC
356e0 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 20 20 _TEST
356f0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
35700 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 ITE_TESTCTRL_FAU
35710 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 LT_INSTALL
35720 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
35730 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
35740 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f BENIGN_MALLOC_HO
35750 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 69 OKS 10.#defi
35760 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
35770 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 RL_PENDING_BYTE
35780 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 11../
35790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
357a0 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53 74 QLite Runtime St
357b0 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c 53 atus {H17200} <S
357c0 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 60200>.** EXPERI
357d0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 MENTAL.**.** Thi
357e0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 s interface is u
357f0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
35800 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 runtime status i
35810 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 nformation.** ab
35820 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d 61 out the preforma
35830 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20 61 nce of SQLite, a
35840 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f nd optionally to
35850 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a 2a reset various.*
35860 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b * highwater mark
35870 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 s. The first ar
35880 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
35890 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a eger code for.**
358a0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 70 61 the specific pa
358b0 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73 75 rameter to measu
358c0 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64 20 re. Recognized
358d0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a integer codes.**
358e0 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d are of the form
358f0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f [SQLITE_STATUS_
35900 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 MEMORY_USED | SQ
35910 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d LITE_STATUS_...]
35920 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 ..** The current
35930 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70 61 value of the pa
35940 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75 72 rameter is retur
35950 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 ned into *pCurre
35960 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68 65 nt..** The highe
35970 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c 75 st recorded valu
35980 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e e is returned in
35990 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20 49 *pHighwater. I
359a0 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c f the.** resetFl
359b0 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e ag is true, then
359c0 20 74 68 65 20 68 69 67 68 65 73 74 20 72 65 63 the highest rec
359d0 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 65 73 ord value is res
359e0 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 et after.** *pHi
359f0 67 68 77 61 74 65 72 20 69 73 20 77 72 69 74 74 ghwater is writt
35a00 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65 74 en. Some paramet
35a10 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 ers do not recor
35a20 64 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a d the highest.**
35a30 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f value. For tho
35a40 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a se parameters.**
35a50 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74 nothing is writ
35a60 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 ten into *pHighw
35a70 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 65 73 ater and the res
35a80 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 etFlag is ignore
35a90 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72 61 d..** Other para
35aa0 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 6f 6e meters record on
35ab0 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 65 72 ly the highwater
35ac0 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68 mark and not th
35ad0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c e current.** val
35ae0 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 20 6c ue. For these l
35af0 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 72 73 atter parameters
35b00 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74 nothing is writ
35b10 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 ten into *pCurre
35b20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 nt..**.** This r
35b30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 outine returns S
35b40 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 QLITE_OK on succ
35b50 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 ess and a non-ze
35b60 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ro.** [error cod
35b70 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a e] on failure..*
35b80 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
35b90 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 20 e is threadsafe
35ba0 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69 but is not atomi
35bb0 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 c. This routine
35bc0 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 can.** called w
35bd0 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65 61 hile other threa
35be0 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 74 ds are running t
35bf0 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66 65 he same or diffe
35c00 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69 rent SQLite.** i
35c10 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 nterfaces. Howe
35c20 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20 72 ver the values r
35c30 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 72 eturned in *pCur
35c40 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 rent and.** *pHi
35c50 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74 20 ghwater reflect
35c60 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53 51 the status of SQ
35c70 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65 6e Lite at differen
35c80 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65 t points in time
35c90 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70 6f .** and it is po
35ca0 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 ssible that anot
35cb0 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68 74 her thread might
35cc0 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72 61 change the para
35cd0 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77 meter.** in betw
35ce0 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77 68 een the times wh
35cf0 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 en *pCurrent and
35d00 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72 65 *pHighwater are
35d10 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 written..**.**
35d20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
35d30 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 0a e3_db_status()].
35d40 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
35d50 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
35d60 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f 70 e3_status(int op
35d70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c , int *pCurrent,
35d80 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 72 int *pHighwater
35d90 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 , int resetFlag)
35da0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
35db0 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d EF: Status Param
35dc0 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20 3c eters {H17250} <
35dd0 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 H17200>.** EXPER
35de0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
35df0 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
35e00 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65 20 tants designate
35e10 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65 various run-time
35e20 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 status paramete
35e30 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 rs.** that can b
35e40 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 e returned by [s
35e50 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
35e60 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
35e70 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
35e80 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64 S_MEMORY_USED</d
35e90 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
35ea0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
35eb0 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f current amount o
35ec0 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 64 f memory checked
35ed0 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 out.** using [s
35ee0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
35ef0 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74 6c , either directl
35f00 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 2e y or indirectly.
35f10 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 20 The.** figure
35f20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d includes calls m
35f30 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ade to [sqlite3_
35f40 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 65 malloc()] by the
35f50 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
35f60 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d and internal mem
35f70 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68 65 ory usage by the
35f80 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
35f90 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 Scratch memory
35fa0 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 .** controlled b
35fb0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
35fc0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61 75 _SCRATCH] and au
35fd0 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61 63 xiliary page-cac
35fe0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e he.** memory con
35ff0 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 trolled by [SQLI
36000 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
36010 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c CHE] is not incl
36020 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20 uded in.** this
36030 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 parameter. The
36040 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 amount returned
36050 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74 68 is the sum of th
36060 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 e allocation.**
36070 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74 65 sizes as reporte
36080 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20 6d d by the xSize m
36090 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65 ethod in [sqlite
360a0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c 3_mem_methods].<
360b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
360c0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c QLITE_STATUS_MAL
360d0 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a LOC_SIZE</dt>.**
360e0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
360f0 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 ter records the
36100 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 largest memory a
36110 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 llocation reques
36120 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b t.** handed to [
36130 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
36140 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
36150 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 65 alloc()] (or the
36160 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65 ir.** internal e
36170 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e quivalents). On
36180 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ly the value ret
36190 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 urned in the.**
361a0 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 *pHighwater para
361b0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
361c0 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 3_status()] is o
361d0 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a f interest. .**
361e0 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 The value writt
361f0 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 en into the *pCu
36200 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 rrent parameter
36210 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 is undefined.</d
36220 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
36230 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 ITE_STATUS_PAGEC
36240 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a ACHE_USED</dt>.*
36250 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
36260 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 eter returns the
36270 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
36280 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 used out of the
36290 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20 6d .** [pagecache m
362a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
362b0 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69 67 that was config
362c0 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20 5b ured using .** [
362d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
362e0 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a 2a GECACHE]. The.*
362f0 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 * value returned
36300 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e 6f is in pages, no
36310 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e t in bytes.</dd>
36320 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
36330 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 E_STATUS_PAGECAC
36340 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e HE_OVERFLOW</dt>
36350 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
36360 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 ameter returns t
36370 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
36380 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68 65 es of page cache
36390 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 .** allocation w
363a0 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 hich could not b
363b0 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20 e statisfied by
363c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
363d0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a 2a IG_PAGECACHE].**
363e0 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 72 buffer and wher
363f0 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 e forced to over
36400 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 flow to [sqlite3
36410 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 _malloc()]. The
36420 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61 6c .** returned val
36430 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 6f ue includes allo
36440 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 cations that ove
36450 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 20 rflowed because
36460 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74 6f they.** where to
36470 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77 65 o large (they we
36480 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 re larger than t
36490 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 he "sz" paramete
364a0 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f r to.** [SQLITE_
364b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
364c0 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69 6f ]) and allocatio
364d0 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 ns that overflow
364e0 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e 6f ed because.** no
364f0 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74 20 space was left
36500 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 in the page cach
36510 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
36520 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
36530 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c 2f PAGECACHE_SIZE</
36540 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
36550 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 parameter record
36560 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 s the largest me
36570 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
36580 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 request.** hande
36590 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65 20 d to [pagecache
365a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
365b0 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c ]. Only the val
365c0 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 ue returned in t
365d0 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 he.** *pHighwate
365e0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b r parameter to [
365f0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
36600 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 ] is of interest
36610 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 . .** The value
36620 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
36630 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 e *pCurrent para
36640 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e meter is undefin
36650 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
36660 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
36670 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f 64 _SCRATCH_USED</d
36680 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
36690 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
366a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 the number of a
366b0 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64 20 llocations used
366c0 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 out of the.** [s
366d0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c cratch memory al
366e0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
366f0 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51 red using.** [SQ
36700 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
36710 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 TCH]. The value
36720 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20 returned is in
36730 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74 allocations, not
36740 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20 53 .** in bytes. S
36750 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74 68 ince a single th
36760 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61 read may only ha
36770 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20 61 ve one scratch a
36780 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74 llocation.** out
36790 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d 65 standing at time
367a0 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 , this parameter
367b0 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74 68 also reports th
367c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 e number of thre
367d0 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72 ads.** using scr
367e0 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20 74 atch memory at t
367f0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 he same time.</d
36800 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
36810 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
36820 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e CH_OVERFLOW</dt>
36830 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
36840 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 ameter returns t
36850 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
36860 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 es of scratch me
36870 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
36880 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e on which could n
36890 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64 ot be statisfied
368a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
368b0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 0a CONFIG_SCRATCH].
368c0 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 ** buffer and wh
368d0 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 ere forced to ov
368e0 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 erflow to [sqlit
368f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 e3_malloc()]. T
36900 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65 74 he values.** ret
36910 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f 76 urned include ov
36920 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65 20 erflows because
36930 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c the requested al
36940 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f 6f location was too
36950 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61 74 .** larger (that
36960 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68 65 is, because the
36970 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 requested alloc
36980 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65 72 ation was larger
36990 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73 7a than the.** "sz
369a0 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b " parameter to [
369b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
369c0 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63 61 RATCH]) and beca
369d0 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20 62 use no scratch b
369e0 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 77 uffer.** slots w
369f0 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a ere available..*
36a00 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 * </dd>.**.** <d
36a10 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
36a20 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64 74 SCRATCH_SIZE</dt
36a30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
36a40 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 rameter records
36a50 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f the largest memo
36a60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
36a70 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 quest.** handed
36a80 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f to [scratch memo
36a90 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 ry allocator].
36aa0 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 Only the value r
36ab0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a eturned in the.*
36ac0 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 * *pHighwater pa
36ad0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
36ae0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 te3_status()] is
36af0 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a of interest. .
36b00 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 ** The value wri
36b10 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 tten into the *p
36b20 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 Current paramete
36b30 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c r is undefined.<
36b40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
36b50 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 52 QLITE_STATUS_PAR
36b60 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a 2a SER_STACK</dt>.*
36b70 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
36b80 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 eter records the
36b90 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72 20 deepest parser
36ba0 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f 6e stack. It is on
36bb0 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 6c ly.** meaningful
36bc0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
36bd0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59 54 mpiled with [YYT
36be0 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50 54 RACKMAXSTACKDEPT
36bf0 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c H].</dd>.** </dl
36c00 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 74 >.**.** New stat
36c10 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d 61 us parameters ma
36c20 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d 20 y be added from
36c30 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a 2f time to time..*/
36c40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
36c50 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 STATUS_MEMORY_US
36c60 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 ED 0.#d
36c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
36c80 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53 TUS_PAGECACHE_US
36c90 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 ED 1.#defi
36ca0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 ne SQLITE_STATUS
36cb0 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 _PAGECACHE_OVERF
36cc0 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65 20 LOW 2.#define
36cd0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 SQLITE_STATUS_SC
36ce0 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20 20 RATCH_USED
36cf0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
36d00 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
36d10 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20 20 CH_OVERFLOW
36d20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
36d30 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 _STATUS_MALLOC_S
36d40 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a 23 IZE 5.#
36d50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
36d60 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43 ATUS_PARSER_STAC
36d70 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 K 6.#def
36d80 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
36d90 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 S_PAGECACHE_SIZE
36da0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
36db0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 SQLITE_STATUS_S
36dc0 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20 20 CRATCH_SIZE
36dd0 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
36de0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
36df0 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74 75 Connection Statu
36e00 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30 32 s {H17500} <S602
36e10 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
36e20 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 TAL.**.** This i
36e30 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
36e40 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e to retrieve run
36e50 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f time status info
36e60 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f 75 rmation .** abou
36e70 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74 61 t a single [data
36e80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
36e90 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 . The first arg
36ea0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
36eb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
36ec0 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 ion object to be
36ed0 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 interrogated.
36ee0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
36ef0 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70 61 ent.** is the pa
36f00 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65 72 rameter to inter
36f10 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e 74 rogate. Current
36f20 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c 6c ly, the only all
36f30 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66 6f owed value.** fo
36f40 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 r the second par
36f50 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49 54 ameter is [SQLIT
36f60 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 E_DBSTATUS_LOOKA
36f70 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 41 SIDE_USED]..** A
36f80 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e dditional option
36f90 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 70 s will likely ap
36fa0 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 20 72 pear in future r
36fb0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
36fc0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 72 e..**.** The cur
36fd0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
36fe0 65 20 72 65 71 75 65 73 74 65 64 20 70 61 72 61 e requested para
36ff0 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 65 6e meter is written
37000 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 61 into *pCur.** a
37010 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 20 69 nd the highest i
37020 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c nstantaneous val
37030 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e ue is written in
37040 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66 0a to *pHiwtr. If.
37050 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67 20 ** the resetFlg
37060 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
37070 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e e highest instan
37080 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 taneous value is
37090 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20 64 .** reset back d
370a0 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72 65 own to the curre
370b0 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 nt value..**.**
370c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
370d0 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e 64 e3_status()] and
370e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 [sqlite3_stmt_s
370f0 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c tatus()]..*/.SQL
37100 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
37110 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f int sqlite3_db_
37120 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a 2c status(sqlite3*,
37130 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 int op, int *pC
37140 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72 2c ur, int *pHiwtr,
37150 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a int resetFlg);.
37160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37170 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 Status Paramete
37180 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 65 20 rs for database
37190 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31 37 connections {H17
371a0 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 2a 520} <H17500>.**
371b0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
371c0 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72 62 73 .** Status verbs
371d0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64 62 for [sqlite3_db
371e0 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a _status()]..**.*
371f0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
37200 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f LITE_DBSTATUS_LO
37210 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f 64 74 OKASIDE_USED</dt
37220 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
37230 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 rameter returns
37240 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6c 6f the number of lo
37250 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 73 okaside memory s
37260 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a lots currently.*
37270 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e 3c 2f * checked out.</
37280 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a dd>.** </dl>.*/.
37290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
372a0 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 BSTATUS_LOOKASID
372b0 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a 0a 2f E_USED 0.../
372c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
372d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
372e0 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 35 30 t Status {H17550
372f0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 } <S60200>.** EX
37300 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
37310 20 45 61 63 68 20 70 72 65 70 61 72 65 64 20 73 Each prepared s
37320 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 61 69 tatement maintai
37330 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 5b 53 ns various.** [S
37340 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 QLITE_STMTSTATUS
37350 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 73 _SORT | counters
37360 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 20 74 ] that measure t
37370 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 he number.** of
37380 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 65 72 times it has per
37390 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 63 20 formed specific
373a0 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 68 65 operations. The
373b0 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 6e 0a se counters can.
373c0 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 6d 6f ** be used to mo
373d0 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 6f 72 nitor the perfor
373e0 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 72 69 mance characteri
373f0 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 72 65 stics of the pre
37400 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
37410 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c nts. For exampl
37420 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72 e, if the number
37430 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 73 20 of table steps
37440 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 73 0a greatly exceeds.
37450 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
37460 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 73 20 table searches
37470 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 2c 20 or result rows,
37480 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e 64 20 that would tend
37490 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a 20 74 to indicate.** t
374a0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 hat the prepared
374b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73 statement is us
374c0 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 ing a full table
374d0 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 68 61 scan rather tha
374e0 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e 20 20 n.** an index.
374f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
37500 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
37510 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 72 65 retrieve and re
37520 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 6c 75 set counter valu
37530 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 72 es from.** a [pr
37540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
37550 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 ]. The first ar
37560 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 70 72 gument is the pr
37570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
37580 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 .** object to be
37590 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 interrogated.
375a0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
375b0 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 ent.** is an int
375c0 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 61 20 eger code for a
375d0 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54 45 specific [SQLITE
375e0 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 _STMTSTATUS_SORT
375f0 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74 | counter].** t
37600 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
37610 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 d. .** The curre
37620 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 nt value of the
37630 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e 74 65 requested counte
37640 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
37650 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 46 6c * If the resetFl
37660 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 g is true, then
37670 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 20 72 the counter is r
37680 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 66 74 eset to zero aft
37690 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 er this.** inter
376a0 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 72 6e face call return
376b0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 s..**.** See als
376c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 o: [sqlite3_stat
376d0 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 us()] and [sqlit
376e0 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e e3_db_status()].
376f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 .*/.SQLITE_EXPER
37700 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
37710 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 te3_stmt_status(
37720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
37730 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 74 46 nt op,int resetF
37740 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lg);../*.** CAPI
37750 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 3REF: Status Par
37760 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 65 70 ameters for prep
37770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 ared statements
37780 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 35 30 {H17570} <H17550
37790 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
377a0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72 L.**.** These pr
377b0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
377c0 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 s define integer
377d0 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 6d 65 codes that name
377e0 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75 counter.** valu
377f0 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 es associated wi
37800 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f th the [sqlite3_
37810 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 20 69 stmt_status()] i
37820 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 nterface..** The
37830 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 meanings of the
37840 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 65 72 various counter
37850 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 s are as follows
37860 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 :.**.** <dl>.**
37870 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 <dt>SQLITE_STMTS
37880 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 TATUS_FULLSCAN_S
37890 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEP</dt>.** <dd>
378a0 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d 62 This is the numb
378b0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
378c0 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 65 70 SQLite has step
378d0 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a ped forward in.*
378e0 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 61 72 * a table as par
378f0 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 62 6c t of a full tabl
37900 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e e scan. Large n
37910 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 73 20 umbers for this
37920 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 counter.** may i
37930 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 75 6e ndicate opportun
37940 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 6f 72 ities for perfor
37950 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e mance improvemen
37960 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 t through .** ca
37970 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 reful use of ind
37980 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ices.</dd>.**.**
37990 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 <dt>SQLITE_STMT
379a0 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e STATUS_SORT</dt>
379b0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 73 20 .** <dd>This is
379c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f the number of so
379d0 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 rt operations th
379e0 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 at have occurred
379f0 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 ..** A non-zero
37a00 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 63 6f value in this co
37a10 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 63 61 unter may indica
37a20 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 te an opportunit
37a30 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d y to.** improvem
37a40 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ent performance
37a50 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 6c 20 through careful
37a60 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c use of indices.<
37a70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
37a80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
37a90 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 55 TE_STMTSTATUS_FU
37aa0 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 20 20 LLSCAN_STEP
37ab0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
37ac0 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 _STMTSTATUS_SORT
37ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 2.
37ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37af0 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 61 63 Custom Page Cac
37b00 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 he Object.** EXP
37b10 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
37b20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 The sqlite3_pcac
37b30 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 71 75 he type is opaqu
37b40 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c 65 6d e. It is implem
37b50 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 ented by.** the
37b60 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65 pluggable module
37b70 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
37b80 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65 re has no knowle
37b90 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69 dge of.** its si
37ba0 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73 ze or internal s
37bb0 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e 65 76 tructure and nev
37bc0 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 74 68 er deals with th
37bd0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 e.** sqlite3_pca
37be0 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 65 70 che object excep
37bf0 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64 t by holding and
37c00 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 65 72 passing pointer
37c10 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65 s.** to the obje
37c20 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73 ct..**.** See [s
37c30 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
37c40 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 69 74 thods] for addit
37c50 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
37c60 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
37c70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 ruct sqlite3_pca
37c80 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 che sqlite3_pcac
37c90 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 he;../*.** CAPI3
37ca0 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e REF: Application
37cb0 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 43 61 Defined Page Ca
37cc0 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 che..** EXPERIME
37cd0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b NTAL.**.** The [
37ce0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
37cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
37d00 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74 CACHE], ...) int
37d10 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65 erface can.** re
37d20 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 72 6e gister an altern
37d30 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65 ative page cache
37d40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
37d50 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 6e by passing in an
37d60 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 .** instance of
37d70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 the sqlite3_pca
37d80 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 72 75 che_methods stru
37d90 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72 cture. The major
37da0 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68 ity of the .** h
37db0 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 eap memory used
37dc0 62 79 20 73 71 6c 69 74 65 20 69 73 20 75 73 65 by sqlite is use
37dd0 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61 d by the page ca
37de0 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 61 74 che to cache dat
37df0 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c a read .** from,
37e00 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 65 20 or ready to be
37e10 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 65 20 written to, the
37e20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 42 database file. B
37e30 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 y implementing a
37e40 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 67 65 .** custom page
37e50 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 68 69 cache using thi
37e60 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c 69 63 s API, an applic
37e70 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f ation can contro
37e80 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69 l more .** preci
37e90 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e 74 20 sely the amount
37ea0 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d of memory consum
37eb0 65 64 20 62 79 20 73 71 6c 69 74 65 2c 20 74 68 ed by sqlite, th
37ec0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 0a e way in which .
37ed0 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 20 69 ** said memory i
37ee0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20 s allocated and
37ef0 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 74 68 released, and th
37f00 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 64 20 e policies used
37f10 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 to .** determine
37f20 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 20 70 exactly which p
37f30 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 62 61 arts of a databa
37f40 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 63 68 se file are cach
37f50 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 ed and for .** h
37f60 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 ow long..**.** T
37f70 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 he contents of t
37f80 68 65 20 73 74 72 75 63 74 75 72 65 20 61 72 65 he structure are
37f90 20 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 69 6e copied to an in
37fa0 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 79 ternal buffer by
37fb0 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 68 69 sqlite.** withi
37fc0 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 n the call to [s
37fd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 0a qlite3_config]..
37fe0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 28 **.** The xInit(
37ff0 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c ) method is call
38000 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
38010 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
38020 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a 3_initialize()].
38030 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79 ** (usually only
38040 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 68 65 once during the
38050 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 lifetime of the
38060 20 70 72 6f 63 65 73 73 29 2e 20 49 74 20 69 73 process). It is
38070 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70 passed.** a cop
38080 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 y of the sqlite3
38090 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e _pcache_methods.
380a0 70 41 72 67 20 76 61 6c 75 65 2e 20 49 74 20 63 pArg value. It c
380b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 an be used to se
380c0 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73 t.** up global s
380d0 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 6d 75 tructures and mu
380e0 74 65 78 65 73 20 72 65 71 75 69 72 65 64 20 62 texes required b
380f0 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 61 67 y the custom pag
38100 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c e cache .** impl
38110 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20 ementation. The
38120 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 xShutdown() meth
38130 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72 6f od is called fro
38140 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 71 m within .** [sq
38150 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
38160 5d 2c 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 ], if the applic
38170 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68 ation invokes th
38180 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20 62 is API. It can b
38190 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 6c 65 e used.** to cle
381a0 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 74 61 an up any outsta
381b0 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73 20 nding resources
381c0 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20 73 before process s
381d0 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 75 hutdown, if requ
381e0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ired..**.** The
381f0 78 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f 64 xCreate() method
38200 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 is used to cons
38210 74 72 75 63 74 20 61 20 6e 65 77 20 63 61 63 68 truct a new cach
38220 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 65 0a e instance. The.
38230 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ** first paramet
38240 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 20 74 er, szPage, is t
38250 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 he size in bytes
38260 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 74 68 of the pages th
38270 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c at must.** be al
38280 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 63 located by the c
38290 61 63 68 65 2e 20 73 7a 50 61 67 65 20 77 69 6c ache. szPage wil
382a0 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 65 72 l not be a power
382b0 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a 2a 20 of two. The.**
382c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
382d0 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20 bPurgeable, is
382e0 74 72 75 65 20 69 66 20 74 68 65 20 63 61 63 68 true if the cach
382f0 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 e being created
38300 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20 will.** be used
38310 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 to cache databas
38320 65 20 70 61 67 65 73 20 72 65 61 64 20 66 72 6f e pages read fro
38330 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 65 64 20 m a file stored
38340 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66 on disk, or.** f
38350 61 6c 73 65 20 69 66 20 69 74 20 69 73 20 75 73 alse if it is us
38360 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d ed for an in-mem
38370 6f 72 79 20 64 61 74 61 62 61 73 65 2e 20 54 68 ory database. Th
38380 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
38390 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e tation.** does n
383a0 6f 74 20 68 61 76 65 20 74 6f 20 64 6f 20 61 6e ot have to do an
383b0 79 74 68 69 6e 67 20 73 70 65 63 69 61 6c 20 62 ything special b
383c0 61 73 65 64 20 6f 6e 20 74 68 65 20 76 61 6c 75 ased on the valu
383d0 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c 65 2c e of bPurgeable,
383e0 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 6c 79 .** it is purely
383f0 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a 2a advisory. .**.*
38400 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 7a 65 * The xCachesize
38410 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 65 () method may be
38420 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 74 called at any t
38430 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 74 6f ime by SQLite to
38440 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 67 67 set the.** sugg
38450 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 63 61 ested maximum ca
38460 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 65 72 che-size (number
38470 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 65 64 of pages stored
38480 20 62 79 29 20 74 68 65 20 63 61 63 68 65 0a 2a by) the cache.*
38490 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 73 65 * instance passe
384a0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
384b0 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 69 73 rgument. This is
384c0 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e 66 69 the value confi
384d0 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 gured using.** t
384e0 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 41 47 he SQLite "[PRAG
384f0 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 22 20 MA cache_size]"
38500 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 74 68 command. As with
38510 20 74 68 65 20 62 50 75 72 67 65 61 62 6c 65 20 the bPurgeable
38520 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 74 68 parameter,.** th
38530 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
38540 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 is not required
38550 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 to do anything
38560 73 70 65 63 69 61 6c 20 77 69 74 68 20 74 68 69 special with thi
38570 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 74 20 69 s.** value, it i
38580 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e s advisory only.
38590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67 65 .**.** The xPage
385a0 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f 64 20 73 count() method s
385b0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 hould return the
385c0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
385d0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 74 currently.** st
385e0 6f 72 65 64 20 69 6e 20 74 68 65 20 63 61 63 68 ored in the cach
385f0 65 20 73 75 70 70 6c 69 65 64 20 61 73 20 61 6e e supplied as an
38600 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a argument..** .*
38610 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 20 6d * The xFetch() m
38620 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f ethod is used to
38630 20 66 65 74 63 68 20 61 20 70 61 67 65 20 61 6e fetch a page an
38640 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 d return a point
38650 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 41 20 er to it. .** A
38660 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 73 20 'page', in this
38670 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 62 75 context, is a bu
38680 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 20 62 ffer of szPage b
38690 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 74 20 ytes aligned at
386a0 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 6f 75 an.** 8-byte bou
386b0 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 65 20 ndary. The page
386c0 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 69 73 to be fetched is
386d0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 determined by t
386e0 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a 20 6d he key. The.** m
386f0 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c 75 65 imimum key value
38700 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 74 20 is 1. After it
38710 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 65 76 has been retriev
38720 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 68 2c ed using xFetch,
38730 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 69 73 the page .** is
38740 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
38750 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 e pinned..**.**
38760 49 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 If the requested
38770 20 70 61 67 65 20 69 73 20 61 6c 72 65 61 64 79 page is already
38780 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 in the page cac
38790 68 65 2c 20 74 68 65 6e 20