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 2e 68 2e 69 $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 32 30 20 32 30 30 38 2f 31 n,v 1.420 2008/1
05f0: 32 2f 31 36 20 31 33 3a 34 36 3a 33 30 20 64 72 2/16 13:46:30 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64 h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 arg.h> /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72 ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 .** These no-op
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 macros are used
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 imental. New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65 recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72 port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31 n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72 specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73 t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22 ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20 of SQLite is a
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61 he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68 " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66 t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 Lite3..** The X
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 mpatible.** but
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 Z value is the
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74 elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 SION #define in
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c ** eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67 uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68 with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 sociated..**.**
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 nteger.**
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 X, Y, and Z.**
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65 are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 major version,
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 LITE_VERSION
1010: 20 20 20 20 20 22 33 2e 36 2e 37 22 0a 23 64 65 "3.6.7".#de
1020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 fine SQLITE_VERS
1030: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 33 30 30 36 ION_NUMBER 3006
1040: 30 30 37 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 007../*.** CAPI3
1050: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
1060: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 brary Version Nu
1070: 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c mbers {H10020} <
1080: 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S60100>.** KEYWO
1090: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 RDS: sqlite3_ver
10a0: 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sion.**.** These
10b0: 20 66 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 features provid
10c0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 e the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 mation as the [S
10e0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a QLITE_VERSION].*
10f0: 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 * and [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 RSION_NUMBER] #d
1110: 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 efines in the he
1120: 61 64 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 ader, but are as
1130: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
1140: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 the library ins
1150: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 tead of the head
1160: 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f er file. Cautio
1170: 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d us programmers m
1180: 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 ight.** include
1190: 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 a check in their
11a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
11b0: 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 verify that.** s
11c0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
11d0: 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 n_number() alway
11e0: 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 s returns the va
11f0: 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 lue.** [SQLITE_V
1200: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a ERSION_NUMBER]..
1210: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1220: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 3_libversion() f
1230: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1240: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
1250: 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e tion as is.** in
1260: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 the sqlite3_ver
1270: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f sion[] string co
1280: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e nstant. The fun
1290: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 ction is provide
12a0: 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 d.** for use in
12b0: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 DLLs since DLL u
12c0: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 sers usually do
12d0: 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63 74 20 not have direct
12e0: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 access to string
12f0: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 .** constants wi
1300: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a thin the DLL..**
1310: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1320: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 **.** {H10021} T
1330: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 he [sqlite3_libv
1340: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d ersion_number()]
1350: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
1360: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
1370: 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 an integer e
1380: 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f qual to [SQLITE_
1390: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e VERSION_NUMBER].
13a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 .**.** {H10022}
13b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 The [sqlite3_ver
13c0: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e sion] string con
13d0: 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 stant shall cont
13e0: 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ain.**
13f0: 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 the text of the
1400: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
1410: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
1420: 48 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c H10023} The [sql
1430: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1440: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c )] function shal
1450: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 l return.**
1460: 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 a pointer t
1470: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1480: 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 ersion] string c
1490: 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 onstant..*/.SQLI
14a0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 TE_EXTERN const
14b0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
14c0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 sion[];.const ch
14d0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 ar *sqlite3_libv
14e0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e ersion(void);.in
14f0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 t sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 sion_number(void
1510: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1520: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 EF: Test To See
1530: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 If The Library I
1540: 73 20 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 s Threadsafe {H1
1550: 30 31 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 0100} <S60100>.*
1560: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 *.** SQLite can
1570: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 be compiled with
1580: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 or without mute
1590: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 xes. When.** th
15a0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
15b0: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 SAFE] C preproce
15c0: 73 73 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 ssor macro 1 or
15d0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
15e0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
15f0: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1600: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
1610: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1620: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
1630: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
1640: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1650: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1660: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1670: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1680: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
1690: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
16a0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
16b0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
16c0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
16d0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
16e0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
16f0: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1700: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1710: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1720: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1730: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1740: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1750: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1760: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1770: 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 ..** The default
1780: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 behavior is for
1790: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 mutexes to be e
17a0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 nabled..**.** Th
17b0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
17c0: 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70 72 be used by a pr
17d0: 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 ogram to make su
17e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
17f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1800: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1810: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1820: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1830: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1840: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1850: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1860: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1870: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
1880: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
1890: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
18a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
18b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
18c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
18d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
18e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
18f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1900: 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 1 then mutexes a
1910: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
1920: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e fault but.** can
1930: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 be fully or par
1940: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 tially disabled
1950: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 using a call to
1960: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
1970: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 )].** with the v
1980: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e erbs [SQLITE_CON
1990: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
19a0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ], [SQLITE_CONFI
19b0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a G_MULTITHREAD],.
19c0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f ** or [SQLITE_CO
19d0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 NFIG_MUTEX]. Th
19e0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
19f0: 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 f this function
1a00: 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 shows.** only th
1a10: 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c e default compil
1a20: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 e-time setting,
1a30: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 not any run-time
1a40: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 changes.** to t
1a50: 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a hat setting..**.
1a60: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
1a70: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
1a80: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
1a90: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
1aa0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tion..**.** INVA
1ab0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
1ac0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 10101} The [sqli
1ad0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
1ae0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
1af0: 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a return zero if.
1b00: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
1b10: 6f 6e 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 only if SQLite w
1b20: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
1b30: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f mutexing code o
1b40: 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 mitted..**.** {H
1b50: 31 30 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 10102} The value
1b60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
1b70: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 [sqlite3_thread
1b80: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e safe()] function
1b90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 .** sha
1ba0: 6c 6c 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 ll remain the sa
1bb0: 6d 65 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 me across calls
1bc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
1bd0: 69 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ig()]..*/.int sq
1be0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1bf0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
1c00: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
1c10: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
1c20: 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 dle {H12000} <S4
1c30: 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0200>.** KEYWORD
1c40: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e S: {database con
1c50: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 nection} {databa
1c60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a se connections}.
1c70: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 **.** Each open
1c80: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
1c90: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 is represented b
1ca0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 y a pointer to a
1cb0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a n instance of.**
1cc0: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 the opaque stru
1cd0: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c cture named "sql
1ce0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 ite3". It is us
1cf0: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 eful to think of
1d00: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 an sqlite3.** p
1d10: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a ointer as an obj
1d20: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ect. The [sqlit
1d30: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
1d40: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
1d50: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1d60: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
1d70: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f faces are its co
1d80: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 nstructors, and
1d90: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
1da0: 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 ].** is its dest
1db0: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 ructor. There a
1dc0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e re many other in
1dd0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 terfaces (such a
1de0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 s.** [sqlite3_pr
1df0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
1e00: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
1e10: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a ction()], and.**
1e20: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1e30: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d imeout()] to nam
1e40: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 e but three) tha
1e50: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e t are methods on
1e60: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f an.** sqlite3 o
1e70: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 bject..*/.typede
1e80: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
1e90: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a sqlite3;../*.**
1ea0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 CAPI3REF: 64-Bi
1eb0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 t Integer Types
1ec0: 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 {H10200} <S10110
1ed0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 >.** KEYWORDS: s
1ee0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
1ef0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
1f00: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
1f10: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
1f20: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
1f30: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
1f40: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
1f50: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
1f60: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
1f70: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
1f80: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
1f90: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
1fa0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
1fb0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
1fc0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
1fd0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
1fe0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
1ff0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
2000: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
2010: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
2020: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
2030: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
2040: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2050: 2a 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b * {H10201} The [
2060: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e sqlite_int64] an
2070: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d [sqlite3_int64
2080: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 ] type shall spe
2090: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 cify.**
20a0: 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
20b0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
20c0: 7b 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 {H10202} The [sq
20d0: 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 lite_uint64] and
20e0: 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 [sqlite3_uint64
20f0: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 ] type shall spe
2100: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 cify.**
2110: 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e a 64-bit unsign
2120: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 ed integer..*/.#
2130: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
2140: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 64_TYPE. typede
2150: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2160: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 YPE sqlite_int64
2170: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
2180: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 gned SQLITE_INT6
2190: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 4_TYPE sqlite_ui
21a0: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 nt64;.#elif defi
21b0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c ned(_MSC_VER) ||
21c0: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 defined(__BORLA
21d0: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 NDC__). typedef
21e0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f __int64 sqlite_
21f0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 int64;. typedef
2200: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 unsigned __int6
2210: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 4 sqlite_uint64;
2220: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 .#else. typedef
2230: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 long long int s
2240: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 qlite_int64;. t
2250: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
2260: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
2270: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e lite_uint64;.#en
2280: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 dif.typedef sqli
2290: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 te_int64 sqlite3
22a0: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 _int64;.typedef
22b0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 sqlite_uint64 sq
22c0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f lite3_uint64;../
22d0: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e *.** If compilin
22e0: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f g for a processo
22f0: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f r that lacks flo
2300: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 ating point supp
2310: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 ort,.** substitu
2320: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 te integer for f
2330: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a loating-point..*
2340: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
2350: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f OMIT_FLOATING_PO
2360: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 INT.# define dou
2370: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 ble sqlite3_int6
2380: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4.#endif../*.**
2390: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e CAPI3REF: Closin
23a0: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e g A Database Con
23b0: 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d nection {H12010}
23c0: 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 <S30100><S40200
23d0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
23e0: 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 tine is the dest
23f0: 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b ructor for the [
2400: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e sqlite3] object.
2410: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2420: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 ons should [sqli
2430: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
2440: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 inalize] all [pr
2450: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2460: 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 s].** and [sqlit
2470: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 e3_blob_close |
2480: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 close] all [BLOB
2490: 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 handles] associ
24a0: 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 ated with.** the
24b0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
24c0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d t prior to attem
24d0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 pting to close t
24e0: 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 he object..** Th
24f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f e [sqlite3_next_
2500: 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 stmt()] interfac
2510: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
2520: 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b locate all.** [
2530: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2540: 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 nts] associated
2550: 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
2560: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 connection] if
2570: 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 desired..** Typi
2580: 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c cal code might l
2590: 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ook like this:.*
25a0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
25b0: 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 ><pre>.** sqlite
25c0: 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 3_stmt *pStmt;.*
25d0: 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 * while( (pStmt
25e0: 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 = sqlite3_next_s
25f0: 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 tmt(db, 0))!=0 )
2600: 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 {.** sq
2610: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 lite3_finalize(p
2620: 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c Stmt);.** }.** <
2630: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
2640: 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c e>.**.** If [sql
2650: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 ite3_close()] is
2660: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 invoked while a
2670: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2680: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 open,.** the tra
2690: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
26a0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
26b0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 back..**.** INV
26c0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
26d0: 48 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 H12011} A succes
26e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
26f0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 lite3_close(C)]
2700: 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 shall destroy th
2710: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 e.** [d
2720: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2730: 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a on] object C..**
2740: 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 .** {H12012} A s
2750: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
2760: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2770: 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 (C)] shall retur
2780: 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a n SQLITE_OK..**.
2790: 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 ** {H12013} A su
27a0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
27b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
27c0: 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 C)] shall releas
27d0: 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 e all.**
27e0: 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 memory and sys
27f0: 74 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 tem resources as
2800: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 sociated with [d
2810: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2820: 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 on].**
2830: 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 C..**.** {H12014
2840: 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c } A call to [sql
2850: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f ite3_close(C)] o
2860: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f n a [database co
2870: 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 nnection] C that
2880: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 .** has
2890: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 one or more ope
28a0: 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 n [prepared stat
28b0: 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 ements] shall fa
28c0: 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 il with.**
28d0: 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 an [SQLITE_B
28e0: 55 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e USY] error code.
28f0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 .**.** {H12015}
2900: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 A call to [sqlit
2910: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 e3_close(C)] whe
2920: 72 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 re C is a NULL p
2930: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 ointer shall.**
2940: 20 20 20 20 20 20 20 20 20 62 65 20 61 20 68 61 be a ha
2950: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 rmless no-op ret
2960: 75 72 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b urning SQLITE_OK
2970: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d ..**.** {H12019}
2980: 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 When [sqlite3_c
2990: 6c 6f 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f lose(C)] is invo
29a0: 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 ked on a [databa
29b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 se connection] C
29c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 .** tha
29d0: 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 t has a pending
29e0: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
29f0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 transaction sha
2a00: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 ll be.**
2a10: 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a rolled back..*
2a20: 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 *.** ASSUMPTIONS
2a30: 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d :.**.** {A12016}
2a40: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 The C parameter
2a50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
2a60: 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 se(C)] must be e
2a70: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 ither a NULL.**
2a80: 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 pointer
2a90: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d or an [sqlite3]
2aa0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 object pointer
2ab0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 obtained.**
2ac0: 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 from [sqlit
2ad0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
2ae0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
2af0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
2b00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2b10: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 )], and not prev
2b20: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a iously closed..*
2b30: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
2b40: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a ose(sqlite3 *);.
2b50: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 ./*.** The type
2b60: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 for a callback f
2b70: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 unction..** This
2b80: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 is legacy and d
2b90: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 eprecated. It i
2ba0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 s included for h
2bb0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d istorical.** com
2bc0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 patibility and i
2bd0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 s not documented
2be0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 ..*/.typedef int
2bf0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 (*sqlite3_callb
2c00: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
2c10: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a har**, char**);.
2c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c30: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 One-Step Query
2c40: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 Execution Interf
2c50: 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 ace {H12100} <S1
2c60: 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
2c70: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
2c80: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
2c90: 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 nvenient way of
2ca0: 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d running one or m
2cb0: 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ore.** SQL state
2cc0: 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 ments without ha
2cd0: 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 ving to write a
2ce0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 lot of C code.
2cf0: 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 The UTF-8 encode
2d00: 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
2d10: 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20 69 nts are passed i
2d20: 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 n as the second
2d30: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2d40: 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 ite3_exec()..**
2d50: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 The statements a
2d60: 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 re evaluated one
2d70: 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 by one until ei
2d80: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 ther an error or
2d90: 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 .** an interrupt
2da0: 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c is encountered,
2db0: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 or until they a
2dc0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 re all done. Th
2dd0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a e 3rd parameter.
2de0: 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 ** is an optiona
2df0: 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 l callback that
2e00: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
2e10: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 for each row of
2e20: 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 any query.** res
2e30: 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 ults produced by
2e40: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2e50: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 nts. The 5th pa
2e60: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 rameter tells wh
2e70: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 ere.** to write
2e80: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
2e90: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 es..**.** The er
2ea0: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 ror message pass
2eb0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 ed back through
2ec0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
2ed0: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 r is held.** in
2ee0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
2ef0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2f00: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f lloc()]. To avo
2f10: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b id a memory leak
2f20: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 ,.** the calling
2f30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
2f40: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 uld call [sqlite
2f50: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 3_free()] on any
2f60: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
2f70: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 e returned throu
2f80: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
2f90: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 eter when it has
2fa0: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a finished using.
2fb0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ** the error mes
2fc0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 sage..**.** If t
2fd0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2fe0: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 in the 2nd para
2ff0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 meter is NULL or
3000: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
3010: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 .** or a string
3020: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 containing only
3030: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 whitespace and c
3040: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
3050: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
3060: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
3070: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
3080: 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 e is not changed
3090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
30a0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
30b0: 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
30c0: 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a ted in terms of.
30d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
30e0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
30f0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
3100: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
3110: 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 ze()]..** The sq
3120: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 lite3_exec() rou
3130: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e tine does nothin
3140: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 g to the databas
3150: 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 e that cannot be
3160: 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c done.** by [sql
3170: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
3190: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
31a0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
31b0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
31c0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d :.**.** {H12101}
31d0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e A successful in
31e0: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
31f0: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c ite3_exec(D,S,C,
3200: 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 A,E)].**
3210: 20 20 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 shall sequenti
3220: 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c ally evaluate al
3230: 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 l of the UTF-8 e
3240: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 ncoded,.**
3250: 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 semicolon-se
3260: 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 parated SQL stat
3270: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 ements in the ze
3280: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
3290: 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 string
32a0: 20 53 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f S within the co
32b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 ntext of the [da
32c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
32d0: 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 n] D..**.** {H12
32e0: 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 102} If the S pa
32f0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
3300: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 te3_exec(D,S,C,A
3310: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 ,E)] is NULL the
3320: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
3330: 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 e actions of the
3340: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
3350: 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 be the same as
3360: 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 if the.**
3370: 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 S parameter w
3380: 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 ere an empty str
3390: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 ing..**.** {H121
33a0: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 04} The return v
33b0: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 alue of [sqlite3
33c0: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 _exec()] shall b
33d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 e [SQLITE_OK] if
33e0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 all.**
33f0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3400: 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 run successfully
3410: 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 and to completi
3420: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 on..**.** {H1210
3430: 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 5} The return va
3440: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f lue of [sqlite3_
3450: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 exec()] shall be
3460: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a an appropriate.
3470: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d ** non-
3480: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
3490: 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 ] if any SQL sta
34a0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a tement fails..**
34b0: 0a 2a 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 .** {H12107} If
34c0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
34d0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
34e0: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c s handed to [sql
34f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 ite3_exec()].**
3500: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
3510: 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 results and the
3520: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 3rd parameter is
3530: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a not NULL, then.
3540: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
3560: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 n specified by t
3570: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
3580: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 shall be.**
3590: 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e invoked on
35a0: 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 ce for each row
35b0: 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a of result..**.**
35c0: 20 7b 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 {H12110} If the
35d0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
35e0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c s a non-zero val
35f0: 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ue then [sqlite3
3600: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 _exec()].**
3610: 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 shall abort
3620: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
3630: 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 nt it is current
3640: 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a ly evaluating,.*
3650: 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 * skip
3660: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 all subsequent S
3670: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 QL statements, a
3680: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
3690: 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ABORT]..**.**
36a0: 7b 48 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 {H12113} The [sq
36b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f lite3_exec()] ro
36c0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 utine shall pass
36d0: 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 its 4th paramet
36e0: 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 er through.**
36f0: 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31 73 as the 1s
3700: 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 t parameter of t
3710: 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a he callback..**.
3720: 2a 2a 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 ** {H12116} The
3730: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3740: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 routine shall s
3750: 65 74 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d et the 2nd param
3760: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 eter of its.**
3770: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b callback
3780: 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 to be the numbe
3790: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
37a0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 the current row
37b0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 of.** r
37c0: 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 esult..**.** {H1
37d0: 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 2119} The [sqlit
37e0: 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 e3_exec()] routi
37f0: 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 ne shall set the
3800: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 3rd parameter o
3810: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 f its.**
3820: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 callback to be
3830: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
3840: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
3850: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 holding the.**
3860: 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 values
3870: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 for each column
3880: 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
3890: 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 esult set row as
38a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 .** obt
38b0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
38c0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
38d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 )]..**.** {H1212
38e0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
38f0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 exec()] routine
3900: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 shall set the 4t
3910: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 h parameter of i
3920: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 ts.** c
3930: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e allback to be an
3940: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
3950: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f rs to strings ho
3960: 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 lding the.**
3970: 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 names of r
3980: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 esult columns as
3990: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
39a0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
39b0: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ame()]..**.** {H
39c0: 31 32 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 12125} If the 3r
39d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
39e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
39f0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 is NULL then.**
3a00: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3a10: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 3_exec()] shall
3a20: 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 silently discard
3a30: 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a query results..
3a40: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 **.** {H12131} I
3a50: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
3a60: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 s while parsing
3a70: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e or evaluating an
3a80: 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 y of the SQL.**
3a90: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 stateme
3aa0: 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 nts in the S par
3ab0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 ameter of [sqlit
3ac0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c e3_exec(D,S,C,A,
3ad0: 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 E)] and if.**
3ae0: 20 20 20 20 20 20 20 74 68 65 20 45 20 70 61 72 the E par
3af0: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ameter is not NU
3b00: 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 LL, then [sqlite
3b10: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 3_exec()] shall
3b20: 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 store.**
3b30: 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f in *E an appro
3b40: 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 priate error mes
3b50: 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 sage written int
3b60: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
3b70: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 d.** fr
3b80: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
3b90: 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 oc()]..**.** {H1
3ba0: 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 2134} The [sqlit
3bb0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c e3_exec(D,S,C,A,
3bc0: 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c E)] routine shal
3bd0: 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 l set the value
3be0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a of.** *
3bf0: 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 E to NULL if E i
3c00: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 s not NULL and t
3c10: 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f here are no erro
3c20: 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 rs..**.** {H1213
3c30: 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 7} The [sqlite3_
3c40: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d exec(D,S,C,A,E)]
3c50: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 function shall
3c60: 73 65 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 set the [error c
3c70: 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ode].**
3c80: 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 and message acc
3c90: 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c essible via [sql
3ca0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c ite3_errcode()],
3cb0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 .** [s
3cc0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
3cd0: 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 errcode()],.**
3ce0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
3cf0: 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 _errmsg()], and
3d00: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
3d10: 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 6()]..**.** {H12
3d20: 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 138} If the S pa
3d30: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
3d40: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 te3_exec(D,S,C,A
3d50: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 ,E)] is NULL or
3d60: 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 an.** e
3d70: 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 mpty string or c
3d80: 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 ontains nothing
3d90: 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 other than white
3da0: 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c space, comments,
3db0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
3dc0: 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 /or semicolons,
3dd0: 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 then results of
3de0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
3df0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
3e00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
3e10: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a ed_errcode()],.*
3e20: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
3e30: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 te3_errmsg()], a
3e40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
3e50: 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 sg16()].**
3e60: 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 shall reset
3e70: 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 to indicate no e
3e80: 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 rrors..**.** ASS
3e90: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
3ea0: 7b 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 {A12141} The fir
3eb0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
3ec0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3ed0: 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 must be an vali
3ee0: 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 d and open.**
3ef0: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
3f00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
3f10: 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 .** {A12142} The
3f20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3f30: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 tion must not be
3f40: 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a closed while.**
3f50: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
3f60: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 e3_exec()] is ru
3f70: 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 nning..**.** {A1
3f80: 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 2143} The callin
3f90: 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c g function shoul
3fa0: 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 d use [sqlite3_f
3fb0: 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a ree()] to free.*
3fc0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d * the m
3fd0: 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d emory that *errm
3fe0: 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 sg is left point
3ff0: 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 ing at once the
4000: 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 error.**
4010: 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 message is no
4020: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a longer needed..*
4030: 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 *.** {A12145} Th
4040: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
4050: 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 text in the 2nd
4060: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
4070: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a lite3_exec()].**
4080: 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 must r
4090: 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 emain unchanged
40a0: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 while [sqlite3_e
40b0: 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e xec()] is runnin
40c0: 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 g..*/.int sqlite
40d0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 3_exec(. sqlite
40e0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 3*,
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4100: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 /* An open
4110: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f database */. co
4120: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 nst char *sql,
4130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4140: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 /* SQL
4150: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 to be evaluated
4160: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 */. int (*callb
4170: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
4180: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 har**,char**),
4190: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 /* Callback func
41a0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
41b0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41d0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 /* 1st argu
41e0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b ment to callback
41f0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 */. char **err
4200: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 msg
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4220: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
4230: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
4240: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4250: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b : Result Codes {
4260: 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e H10210} <S10700>
4270: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
4280: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 LITE_OK {error c
4290: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 ode} {error code
42a0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
42b0: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 {result code} {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a esult codes}.**.
42d0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 ** Many SQLite f
42e0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
42f0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c an integer resul
4300: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 t code from the
4310: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 set shown.** her
4320: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e e in order to in
4330: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 dicates success
4340: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a or failure..**.*
4350: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 * New error code
4360: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
4370: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e n future version
4380: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
4390: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 ** See also: [SQ
43a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 LITE_IOERR_READ
43b0: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c | extended resul
43c0: 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 t codes].*/.#def
43d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 ine SQLITE_OK
43e0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 0 /* S
43f0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 uccessful result
4400: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 */./* beginning
4410: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 -of-error-codes
4420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4430: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 E_ERROR 1
4440: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 /* SQL error
4450: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 or missing datab
4460: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
4470: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 QLITE_INTERNAL
4480: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 2 /* Intern
4490: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 al logic error i
44a0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 n SQLite */.#def
44b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 ine SQLITE_PERM
44c0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 3 /* A
44d0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e ccess permission
44e0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
44f0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ne SQLITE_ABORT
4500: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 4 /* Ca
4510: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
4520: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 equested an abor
4530: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4540: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 ITE_BUSY
4550: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 5 /* The data
4560: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 base file is loc
4570: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
4580: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 QLITE_LOCKED
4590: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 6 /* A tabl
45a0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 e in the databas
45b0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
45d0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f MEM 7 /
45e0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 * A malloc() fai
45f0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 led */.#define S
4600: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 QLITE_READONLY
4610: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 8 /* Attemp
4620: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 t to write a rea
4630: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a donly database *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4650: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 _INTERRUPT 9
4660: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 /* Operation t
4670: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c erminated by sql
4680: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
4690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
46a0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 E_IOERR 10
46b0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 /* Some kind
46c0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f of disk I/O erro
46d0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 r occurred */.#d
46e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
46f0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a RUPT 11 /*
4700: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 The database di
4710: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 sk image is malf
4720: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ormed */.#define
4730: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
4740: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 12 /* NOT
4750: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 USED. Table or r
4760: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 ecord not found
4770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4780: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 E_FULL 13
4790: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 /* Insertion
47a0: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 failed because d
47b0: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 atabase is full
47c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
47d0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 E_CANTOPEN 14
47e0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 /* Unable to
47f0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
4800: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
4810: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f e SQLITE_PROTOCO
4820: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 L 15 /* NOT
4830: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 USED. Database
4840: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 lock protocol er
4850: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
4860: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 QLITE_EMPTY
4870: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 16 /* Databa
4880: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 se is empty */.#
4890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 define SQLITE_SC
48a0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f HEMA 17 /
48b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 * The database s
48c0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f chema changed */
48d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48e0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 TOOBIG 18
48f0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c /* String or BL
4900: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 OB exceeds size
4910: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 limit */.#define
4920: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
4930: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 NT 19 /* Abor
4940: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 t due to constra
4950: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f int violation */
4960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4970: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 MISMATCH 20
4980: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 /* Data type mi
4990: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e smatch */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 e SQLITE_MISUSE
49b0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 21 /* Lib
49c0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 rary used incorr
49d0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ectly */.#define
49e0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 SQLITE_NOLFS
49f0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 22 /* Uses
4a00: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 OS features not
4a10: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f supported on ho
4a20: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 st */.#define SQ
4a30: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 LITE_AUTH
4a40: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 23 /* Authori
4a50: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f zation denied */
4a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4a70: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 FORMAT 24
4a80: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 /* Auxiliary da
4a90: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 tabase format er
4aa0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
4ab0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 QLITE_RANGE
4ac0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 25 /* 2nd pa
4ad0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
4ae0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 e3_bind out of r
4af0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ange */.#define
4b00: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 SQLITE_NOTADB
4b10: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 26 /* File
4b20: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e opened that is n
4b30: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 ot a database fi
4b40: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 LITE_ROW
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 100 /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 DONE 101
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 executing */./*
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 I3REF: Extended
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
4c20: 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 0220} <S10700>.*
4c30: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 * KEYWORDS: {ext
4c40: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
4c50: 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f } {extended erro
4c60: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
4c70: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
4c80: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 result code} {ex
4c90: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4ca0: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 des}.**.** In it
4cb0: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 s default config
4cc0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 uration, SQLite
4cd0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 API routines ret
4ce0: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e urn one of 26 in
4cf0: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 teger.** [SQLITE
4d00: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 _OK | result cod
4d10: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 es]. However, e
4d20: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 xperience has sh
4d30: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 own that many of
4d40: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 .** these result
4d50: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 codes are too c
4d60: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 oarse-grained.
4d70: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 They do not prov
4d80: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 ide as.** much i
4d90: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
4da0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f problems as pro
4db0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c grammers might l
4dc0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f ike. In an effo
4dd0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 rt to.** address
4de0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 this, newer ver
4df0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
4e00: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 (version 3.3.8 a
4e10: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 nd later) includ
4e20: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 e.** support for
4e30: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 additional resu
4e40: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 lt codes that pr
4e50: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 ovide more detai
4e60: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a led information.
4e70: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e ** about errors.
4e80: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 The extended re
4e90: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 sult codes are e
4ea0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
4eb0: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 ed.** on a per d
4ec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4ed0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 on basis using t
4ee0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
4ef0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
4f00: 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a odes()] API..**.
4f10: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 ** Some of the a
4f20: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 vailable extende
4f30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
4f40: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a re listed here..
4f50: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 ** One may expec
4f60: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
4f70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4f80: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 codes will be ex
4f90: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d pand.** over tim
4fa0: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 e. Software tha
4fb0: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 t uses extended
4fc0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f result codes sho
4fd0: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f uld expect.** to
4fe0: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 see new result
4ff0: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 codes in future
5000: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
5010: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 te..**.** The SQ
5020: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 LITE_OK result c
5030: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 ode will never b
5040: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 e extended. It
5050: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 will always.** b
5060: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a e exactly zero..
5070: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
5080: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d :.**.** {H10223}
5090: 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 The symbolic na
50a0: 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 me for an extend
50b0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 ed result code s
50c0: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a hall contains.**
50d0: 20 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 a rela
50e0: 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 ted primary resu
50f0: 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 lt code as a pre
5100: 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 fix..**.** {H102
5110: 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 24} Primary resu
5120: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 lt code names sh
5130: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 all contain a si
5140: 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 ngle "_" charact
5150: 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 er..**.** {H1022
5160: 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 5} Extended resu
5170: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 lt code names sh
5180: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 all contain two
5190: 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 or more "_" char
51a0: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 acters..**.** {H
51b0: 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 10226} The numer
51c0: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 ic value of an e
51d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
51e0: 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 ode shall contai
51f0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
5200: 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 numeric value
5210: 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e of its correspon
5220: 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 ding primary res
5230: 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 ult code in.**
5240: 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 its leas
5250: 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 t significant 8
5260: 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 bits..*/.#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
5280: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
52c0: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
52e0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
5300: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
5340: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
5360: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5370: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
5380: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
5390: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
53a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
53b0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
53c0: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
53d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
53e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
53f0: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
5400: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5410: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
5420: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5430: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
5440: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5450: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
5460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5470: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
5480: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5490: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
54a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
54b0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
54c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
54d0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
54e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
54f0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
5500: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5510: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
5520: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5530: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
5540: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5550: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
5560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5570: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
5580: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5590: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
55b0: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
55c0: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
55d0: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
55f0: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5610: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
5620: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5630: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 OERR_CLOSE
5640: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5650: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a OERR | (16<<8)).
5660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5670: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 OERR_DIR_CLOSE
5680: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5690: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a OERR | (17<<8)).
56a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
56b0: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 Flags For File
56c0: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 Open Operations
56d0: 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 {H10230} <H11120
56e0: 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a > <H12700>.**.**
56f0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 These bit value
5700: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
5710: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a or use in the.**
5720: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
5730: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f o the [sqlite3_o
5740: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
5750: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 ace and.** in th
5760: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
5770: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
5780: 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 hod of the.** [s
5790: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
57a0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
57b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
57c0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
57d0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
57e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
57f0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
5800: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 000002.#define S
5810: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
5820: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
5830: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 000004.#define S
5840: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
5850: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
5860: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 000008.#define S
5870: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
5880: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
5890: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
58a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
58b0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
58c0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
58d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
58e0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
58f0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 000200.#define S
5900: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
5910: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
5920: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 000400.#define S
5930: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
5940: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
5950: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
5960: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
5970: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
5980: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
5990: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
59a0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
59b0: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 002000.#define S
59c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
59d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
59e0: 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 004000.#define S
59f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
5a00: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
5a10: 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 008000.#define S
5a20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
5a30: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
5a40: 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 010000../*.** CA
5a50: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 PI3REF: Device C
5a60: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b haracteristics {
5a70: 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e H10240} <H11120>
5a80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
5a90: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d ceCapabilities m
5aa0: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 ethod of the [sq
5ab0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5ac0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 ].** object retu
5ad0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 rns an integer w
5ae0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 hich is a vector
5af0: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a of the these.**
5b00: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 bit values expr
5b10: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 essing I/O chara
5b20: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 cteristics of th
5b30: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a e mass storage.*
5b40: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f * device that ho
5b50: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 lds the file tha
5b60: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 t the [sqlite3_i
5b70: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 o_methods].** re
5b80: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 fers to..**.** T
5b90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
5ba0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 ATOMIC property
5bb0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 means that all w
5bc0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 rites of.** any
5bd0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e size are atomic.
5be0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
5bf0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c AP_ATOMICnnn val
5c00: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 ues.** mean that
5c10: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b writes of block
5c20: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 s that are nnn b
5c30: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 ytes in size and
5c40: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 .** are aligned
5c50: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 to an address wh
5c60: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ich is an intege
5c70: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a r multiple of.**
5c80: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e nnn are atomic.
5c90: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
5ca0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 AP_SAFE_APPEND v
5cb0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 alue means.** th
5cc0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 at when data is
5cd0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 appended to a fi
5ce0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 le, the data is
5cf0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 appended.** firs
5d00: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 t then the size
5d10: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 of the file is e
5d20: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 xtended, never t
5d30: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 he other.** way
5d40: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c around. The SQL
5d50: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
5d60: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 TIAL property me
5d70: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f ans that.** info
5d80: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 rmation is writt
5d90: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 en to disk in th
5da0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 e same order as
5db0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 calls.** to xWri
5dc0: 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 te()..*/.#define
5dd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5de0: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 OMIC 0x
5df0: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 00000001.#define
5e00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e10: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 OMIC512 0x
5e20: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 00000002.#define
5e30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e40: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 OMIC1K 0x
5e50: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
5e60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e70: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 OMIC2K 0x
5e80: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
5e90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5ea0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 OMIC4K 0x
5eb0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
5ec0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5ed0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 OMIC8K 0x
5ee0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 00000020.#define
5ef0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5f00: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 OMIC16K 0x
5f10: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
5f20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5f30: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 OMIC32K 0x
5f40: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 00000080.#define
5f50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5f60: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 OMIC64K 0x
5f70: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
5f80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
5f90: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 FE_APPEND 0x
5fa0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
5fb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
5fc0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 QUENTIAL 0x
5fd0: 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 00000400../*.**
5fe0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
5ff0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 ocking Levels {H
6000: 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 10250} <H11120>
6010: 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 <H11310>.**.** S
6020: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f QLite uses one o
6030: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 f these integer
6040: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
6050: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 cond.** argument
6060: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b to calls it mak
6070: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 es to the xLock(
6080: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 ) and xUnlock()
6090: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e methods.** of an
60a0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
60b0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f hods] object..*/
60c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
60d0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 LOCK_NONE
60e0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
60f0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 ITE_LOCK_SHARED
6100: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
6110: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 SQLITE_LOCK_RES
6120: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 ERVED 2.#de
6130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
6140: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 _PENDING 3
6150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6160: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 LOCK_EXCLUSIVE
6170: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 4../*.** CAPI
6180: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 3REF: Synchroniz
6190: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 ation Type Flags
61a0: 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 {H10260} <H1112
61b0: 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 0>.**.** When SQ
61c0: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
61d0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 xSync() method
61e0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 of an.** [sqlite
61f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
6200: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 ject it uses a c
6210: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
6220: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
6230: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
6240: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ond argument..**
6250: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c .** When the SQL
6260: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
6270: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 Y flag is used,
6280: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
6290: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 e.** sync operat
62a0: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 ion only needs t
62b0: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 o flush data to
62c0: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 mass storage. I
62d0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 node.** informat
62e0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 ion need not be
62f0: 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c flushed. The SQL
6300: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
6310: 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f flag means.** to
6320: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e use normal fsyn
6330: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 c() semantics. T
6340: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 he SQLITE_SYNC_F
6350: 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a ULL flag means.*
6360: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 * to use Mac OS
6370: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
6380: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e instead of fsyn
6390: 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 c()..*/.#define
63a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
63b0: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 AL 0x0000
63c0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
63d0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 _SYNC_FULL
63e0: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 0x00003.#def
63f0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
6400: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 DATAONLY 0x
6410: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 00010../*.** CAP
6420: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
6430: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 ace Open File Ha
6440: 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 ndle {H11110} <S
6450: 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 20110>.**.** An
6460: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
6470: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
6480: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e an open file in
6490: 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 the OS.** inter
64a0: 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 face layer. Ind
64b0: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 ividual OS inter
64c0: 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 face implementat
64d0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
64e0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
64f0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
6500: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
6510: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
6520: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
6530: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
6540: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
6550: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
6560: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
6570: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
6580: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
6590: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
65a0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
65b0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
65c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
65d0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
65e0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
65f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
6600: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
6610: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
6620: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
6630: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
6640: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
6650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
6660: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
6670: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
6680: 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 ds Object {H1112
6690: 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 0} <S20110>.**.*
66a0: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 * Every file ope
66b0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 ned by the [sqli
66c0: 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d te3_vfs] xOpen m
66d0: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 ethod populates
66e0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 an.** [sqlite3_f
66f0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c ile] object (or,
6700: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 more commonly,
6710: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 a subclass of th
6720: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 e.** [sqlite3_fi
6730: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 le] object) with
6740: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
6750: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
6760: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 s object..** Thi
6770: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
6780: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 the methods use
6790: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 d to perform var
67a0: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a ious operations.
67b0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f ** against the o
67c0: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 pen file represe
67d0: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c nted by the [sql
67e0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
67f0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 t..**.** The fla
6800: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
6810: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
6820: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
6830: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
6840: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
6850: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
6860: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
6870: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
6880: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
6890: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 is a Mac OS X st
68a0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
68b0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
68c0: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
68d0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
68e0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
68f0: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
6900: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
6910: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
6920: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
6930: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
6940: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
6950: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
6960: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
6970: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
6980: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
6990: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
69a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
69b0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
69c0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
69d0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
69e0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
69f0: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
6a00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
6a10: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
6a20: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
6a30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
6a40: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
6a50: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
6a60: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
6a70: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
6a80: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
6a90: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
6aa0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
6ab0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
6ac0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
6ad0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
6ae0: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
6af0: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
6b00: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
6b10: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
6b20: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
6b30: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
6b40: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
6b50: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
6b60: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
6b70: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
6b80: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
6b90: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
6ba0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
6bb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
6bc0: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
6bd0: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
6be0: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
6bf0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
6c00: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
6c10: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
6c20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
6c30: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
6c40: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
6c50: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
6c60: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
6c70: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
6c80: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
6c90: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
6ca0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
6cb0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
6cc0: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
6cd0: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
6ce0: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
6cf0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
6d00: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
6d10: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
6d20: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
6d30: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
6d40: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
6d50: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
6d60: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
6d70: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
6d80: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
6d90: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
6da0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
6db0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
6dc0: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
6dd0: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
6de0: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
6df0: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
6e00: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
6e10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
6e20: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f CKSTATE | list o
6e30: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 f opcodes] less
6e40: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 than 100 is avai
6e50: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 lable..** Applic
6e60: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 ations that defi
6e70: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c ne a custom xFil
6e80: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
6e90: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 should use opcod
6ea0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 es.** greater th
6eb0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 an 100 to avoid
6ec0: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a conflicts..**.**
6ed0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 The xSectorSize
6ee0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
6ef0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a s the sector siz
6f00: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 e of the.** devi
6f10: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 ce that underlie
6f20: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 s the file. The
6f30: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 sector size is
6f40: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 the.** minimum w
6f50: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 rite that can be
6f60: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f performed witho
6f70: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a ut disturbing.**
6f80: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 other bytes in
6f90: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 the file. The x
6fa0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
6fb0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f stics().** metho
6fc0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 d returns a bit
6fd0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e vector describin
6fe0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 g behaviors of t
6ff0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
7000: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c device:.**.** <
7010: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
7020: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7030: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7040: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
7050: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 2].** <li> [SQLI
7060: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
7070: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7080: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 TE_IOCAP_ATOMIC2
7090: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
70a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
70b0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
70c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
70d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
70e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
70f0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 6K].** <li> [SQL
7100: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7110: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 32K].** <li> [SQ
7120: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7130: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C64K].** <li> [S
7140: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
7150: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e _APPEND].** <li>
7160: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
7170: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f EQUENTIAL].** </
7180: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ul>.**.** The SQ
7190: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
71a0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
71b0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
71c0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
71d0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
71e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
71f0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
7200: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
7210: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
7220: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
7230: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
7240: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
7250: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
7260: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
7270: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
7280: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
7290: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
72a0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
72b0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
72c0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
72d0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
72e0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
72f0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
7300: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
7310: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
7320: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
7330: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
7340: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
7350: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
7360: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
7370: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
7380: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
7390: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
73a0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
73b0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
73c0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 .**.** If xRead(
73d0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 ) returns SQLITE
73e0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
73f0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 D it must also f
7400: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e ill.** in the un
7410: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 read portions of
7420: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 the buffer with
7430: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 zeros. A VFS t
7440: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 hat.** fails to
7450: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
7460: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d reads might seem
7470: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 to work. Howev
7480: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 er,.** failure t
7490: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
74a0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 t reads will eve
74b0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a ntually lead to.
74c0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 ** database corr
74d0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 uption..*/.typed
74e0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
74f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 3_io_methods sql
7500: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b ite3_io_methods;
7510: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
7520: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 io_methods {. i
7530: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
7540: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
7550: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
7560: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 nt (*xRead)(sqli
7570: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a te3_file*, void*
7580: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
7590: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
75a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 ;. int (*xWrite
75b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
75c0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
75d0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
75e0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
75f0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
7600: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
7610: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 sqlite3_int64 si
7620: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ze);. int (*xSy
7630: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 nc)(sqlite3_file
7640: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 *, int flags);.
7650: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 int (*xFileSize
7660: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7670: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
7680: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a pSize);. int (*
7690: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 xLock)(sqlite3_f
76a0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
76b0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c t (*xUnlock)(sql
76c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
76d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b ;. int (*xCheck
76e0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 ReservedLock)(sq
76f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
7700: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e *pResOut);. in
7710: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c t (*xFileControl
7720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7730: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 int op, void *p
7740: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Arg);. int (*xS
7750: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 ectorSize)(sqlit
7760: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
7770: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 (*xDeviceCharac
7780: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 teristics)(sqlit
7790: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 e3_file*);. /*
77a0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f Additional metho
77b0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ds may be added
77c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
77d0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 es */.};../*.**
77e0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 CAPI3REF: Standa
77f0: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 rd File Control
7800: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d Opcodes {H11310}
7810: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30800>.**.**
7820: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
7830: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
7840: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
7850: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
7860: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
7870: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
7880: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 bject and for th
7890: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
78a0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e control()].** in
78b0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
78c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
78d0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f _LOCKSTATE] opco
78e0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
78f0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
7900: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
7910: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
7920: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 l method to writ
7930: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 e the current st
7940: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f ate of.** the lo
7950: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 ck (one of [SQLI
7960: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b TE_LOCK_NONE], [
7970: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
7980: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ED],.** [SQLITE_
7990: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 LOCK_RESERVED],
79a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
79b0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 DING], or [SQLIT
79c0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
79d0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e ]).** into an in
79e0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 teger that the p
79f0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 Arg argument poi
7a00: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 nts to. This cap
7a10: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 ability.** is us
7a20: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
7a30: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 g and only needs
7a40: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
7a50: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
7a60: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e T.** is defined.
7a70: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
7a80: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
7a90: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 TE 1.#def
7aa0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c ine SQLITE_GET_L
7ab0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
7ac0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
7ad0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
7ae0: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 FILE 3.#def
7af0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f ine SQLITE_LAST_
7b00: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 ERRNO
7b10: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
7b20: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c REF: Mutex Handl
7b30: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 e {H17110} <S201
7b40: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 30>.**.** The mu
7b50: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 tex module withi
7b60: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 n SQLite defines
7b70: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
7b80: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 to be an.** abs
7b90: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 tract type for a
7ba0: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 mutex object.
7bb0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
7bc0: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 never looks.** a
7bd0: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 t the internal r
7be0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 epresentation of
7bf0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 an [sqlite3_mut
7c00: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a ex]. It only.**
7c10: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e deals with poin
7c20: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c ters to the [sql
7c30: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 ite3_mutex] obje
7c40: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 ct..**.** Mutexe
7c50: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
7c60: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
7c70: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a ex_alloc()]..*/.
7c80: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
7c90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c qlite3_mutex sql
7ca0: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a ite3_mutex;../*.
7cb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
7cc0: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 Interface Object
7cd0: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 {H11140} <S2010
7ce0: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 0>.**.** An inst
7cf0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
7d00: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
7d10: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
7d20: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
7d30: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
7d40: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
7d50: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
7d60: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
7d70: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
7d80: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
7d90: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
7da0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a file system"..*
7db0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f *.** The value o
7dc0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 f the iVersion f
7dd0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c ield is initiall
7de0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c y 1 but may be l
7df0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 arger in.** futu
7e00: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
7e10: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e QLite. Addition
7e20: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 al fields may be
7e30: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 appended to thi
7e40: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e s.** object when
7e50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
7e60: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 lue is increased
7e70: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
7e80: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 structure.** of
7e90: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
7ea0: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 object changes
7eb0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 in the transacti
7ec0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 on between.** SQ
7ed0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
7ee0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 .9 and 3.6.0 and
7ef0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
7f00: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a n field was not.
7f10: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ** modified..**.
7f20: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
7f30: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
7f40: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
7f50: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
7f60: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
7f70: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
7f80: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
7f90: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
7fa0: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
7fb0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
7fc0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
7fd0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
7fe0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
7ff0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
8000: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
8010: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
8020: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
8030: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
8040: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
8050: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
8060: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
8070: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
8080: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
8090: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
80a0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
80b0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
80c0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
80d0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
80e0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
80f0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
8100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
8110: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
8120: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
8130: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
8140: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
8150: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
8160: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
8170: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
8180: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
8190: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
81a0: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
81b0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
81c0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
81d0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
81e0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
81f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
8200: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
8210: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
8220: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
8230: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
8240: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
8250: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
8260: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
8270: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
8280: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
8290: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
82a0: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
82b0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
82c0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
82d0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 * SQLite will gu
82e0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 arantee that the
82f0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
8300: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a eter to xOpen.**
8310: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c is either a NUL
8320: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 L pointer or str
8330: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ing obtained.**
8340: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 from xFullPathna
8350: 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 me(). SQLite fu
8360: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 rther guarantees
8370: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 that.** the str
8380: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ing will be vali
8390: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 d and unchanged
83a0: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 until xClose() i
83b0: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 s.** called. Bec
83c0: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 ause of the prev
83d0: 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a ious sentense,.*
83e0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 * the [sqlite3_f
83f0: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 ile] can safely
8400: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 store a pointer
8410: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 to the.** filena
8420: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 me if it needs t
8430: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 o remember the f
8440: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 ilename for some
8450: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 reason..** If t
8460: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
8470: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 ameter is xOpen
8480: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
8490: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 r then xOpen.**
84a0: 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 must invite its
84b0: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 own temporary na
84c0: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e me for the file.
84d0: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a Whenever the .
84e0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 ** xFilename par
84f0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 ameter is NULL i
8500: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 t will also be t
8510: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
8520: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 .** flags parame
8530: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 ter will include
8540: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
8550: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a LETEONCLOSE]..**
8560: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
8570: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 gument to xOpen(
8580: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 ) includes all b
8590: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 its set in.** th
85a0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
85b0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
85c0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 n_v2()]. Or if
85d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
85e0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
85f0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 open16()] is use
8600: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e d, then flags in
8610: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a cludes at least.
8620: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
8630: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
8640: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
8650: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 ]. .** If xOpen(
8660: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 ) opens a file r
8670: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 ead-only then it
8680: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 sets *pOutFlags
8690: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b to.** include [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
86b0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 ONLY]. Other bi
86c0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 ts in *pOutFlags
86d0: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a may be set..**.
86e0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ** SQLite will a
86f0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
8700: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
8710: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 gs to the xOpen(
8720: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e ).** call, depen
8730: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 ding on the obje
8740: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a ct being opened:
8750: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
8760: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
8770: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c N_MAIN_DB].** <l
8780: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
8790: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _MAIN_JOURNAL].*
87a0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
87b0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a OPEN_TEMP_DB].**
87c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
87d0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
87e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
87f0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
8800: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b T_DB].** <li> [
8810: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
8820: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
8840: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a STER_JOURNAL].**
8850: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
8860: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d file I/O implem
8870: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 entation can use
8880: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 the object type
8890: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 flags to.** cha
88a0: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 nge the way it d
88b0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e eals with files.
88c0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 For example, a
88d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a n application.**
88e0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 that does not c
88f0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 are about crash
8900: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c recovery or roll
8910: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a back might make.
8920: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 ** the open of a
8930: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 journal file a
8940: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 no-op. Writes t
8950: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 o this journal w
8960: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 ould.** also be
8970: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 no-ops, and any
8980: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 attempt to read
8990: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c the journal woul
89a0: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 d return.** SQLI
89b0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 TE_IOERR. Or th
89c0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
89d0: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 might recognize
89e0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 that a database
89f0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 .** file will be
8a00: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 doing page-alig
8a10: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 ned sector reads
8a20: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 and writes in a
8a30: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 random.** order
8a40: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 and set up its
8a50: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 I/O subsystem ac
8a60: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a cordingly..**.**
8a70: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c SQLite might al
8a80: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
8a90: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
8aa0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d s to the xOpen m
8ab0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
8ac0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
8ad0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
8ae0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 LOSE].** <li> [S
8af0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
8b00: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a SIVE].** </ul>.*
8b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
8b20: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
8b30: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 OSE] flag means
8b40: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
8b50: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 be.** deleted wh
8b60: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e en it is closed.
8b70: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 The [SQLITE_OP
8b80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
8b90: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 ].** will be set
8ba0: 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 for TEMP datab
8bb0: 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 ases, journals a
8bc0: 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 nd for subjourna
8bd0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ls..**.** The [S
8be0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
8bf0: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 SIVE] flag means
8c00: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
8c10: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f be opened.** fo
8c20: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
8c30: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 ss. This flag i
8c40: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 s set for all fi
8c50: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f les except.** fo
8c60: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 r the main datab
8c70: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 ase file..**.**
8c80: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c At least szOsFil
8c90: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 e bytes of memor
8ca0: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 y are allocated
8cb0: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 by SQLite.** to
8cc0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 hold the [sqlit
8cd0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 e3_file] structu
8ce0: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 re passed as the
8cf0: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 third.** argume
8d00: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 nt to xOpen. Th
8d10: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 e xOpen method d
8d20: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a oes not have to.
8d30: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 ** allocate the
8d40: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 structure; it sh
8d50: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 ould just fill i
8d60: 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t in..**.** The
8d70: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
8d80: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 o xAccess() may
8d90: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 be [SQLITE_ACCES
8da0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 S_EXISTS].** to
8db0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 test for the exi
8dc0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 stence of a file
8dd0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 , or [SQLITE_ACC
8de0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 ESS_READWRITE] t
8df0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 o.** test whethe
8e00: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 r a file is read
8e10: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c able and writabl
8e20: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
8e30: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f CESS_READ].** to
8e40: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
8e50: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 file is at least
8e60: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 readable. The
8e70: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a file can be a.*
8e80: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a * directory..**.
8e90: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ** SQLite will a
8ea0: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 lways allocate a
8eb0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 t least mxPathna
8ec0: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 me+1 bytes for t
8ed0: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 he.** output buf
8ee0: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d fer xFullPathnam
8ef0: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 e. The exact si
8f00: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 ze of the output
8f10: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c buffer.** is al
8f20: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 so passed as a p
8f30: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 arameter to both
8f40: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 methods. If th
8f50: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a e output buffer.
8f60: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 ** is not large
8f70: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f enough, [SQLITE_
8f80: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 CANTOPEN] should
8f90: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 be returned. Si
8fa0: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 nce this is.** h
8fb0: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 andled as a fata
8fc0: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 l error by SQLit
8fd0: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 e, vfs implement
8fe0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e ations should en
8ff0: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 deavor.** to pre
9000: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 vent this by set
9010: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 ting mxPathname
9020: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c to a sufficientl
9030: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a y large value..*
9040: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d *.** The xRandom
9050: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 ness(), xSleep()
9060: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 , and xCurrentTi
9070: 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a me() interfaces.
9080: 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 ** are not stric
9090: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 tly a part of th
90a0: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 e filesystem, bu
90b0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e t they are.** in
90c0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 cluded in the VF
90d0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 S structure for
90e0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a completeness..**
90f0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
9100: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 () function atte
9110: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e mpts to return n
9120: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f Bytes bytes.** o
9130: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 f good-quality r
9140: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a andomness into z
9150: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e Out. The return
9160: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 value is.** the
9170: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f actual number o
9180: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f f bytes of rando
9190: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a mness obtained..
91a0: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 ** The xSleep()
91b0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 method causes th
91c0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 e calling thread
91d0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 to sleep for at
91e0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 .** least the nu
91f0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 mber of microsec
9200: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 onds given. The
9210: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a xCurrentTime().
9220: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e ** method return
9230: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e s a Julian Day N
9240: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 umber for the cu
9250: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 rrent date and t
9260: 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 ime..**.*/.typed
9270: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
9280: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 3_vfs sqlite3_vf
9290: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
92a0: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 3_vfs {. int iV
92b0: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 ersion;
92c0: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 /* Structure
92d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a version number *
92e0: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 /. int szOsFile
92f0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ; /*
9300: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 Size of subclass
9310: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ed sqlite3_file
9320: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e */. int mxPathn
9330: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ame; /*
9340: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 Maximum file pa
9350: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f thname length */
9360: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a . sqlite3_vfs *
9370: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e pNext; /* N
9380: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 ext registered V
9390: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 FS */. const ch
93a0: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 ar *zName;
93b0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 /* Name of this
93c0: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 virtual file sy
93d0: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a stem */. void *
93e0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 pAppData;
93f0: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f /* Pointer to
9400: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 application-spe
9410: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 cific data */.
9420: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c int (*xOpen)(sql
9430: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
9440: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 char *zName, sq
9450: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 lite3_file*,.
9460: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 int
9470: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 flags, int *pOut
9480: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a Flags);. int (*
9490: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 xDelete)(sqlite3
94a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
94b0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 r *zName, int sy
94c0: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a ncDir);. int (*
94d0: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 xAccess)(sqlite3
94e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
94f0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c r *zName, int fl
9500: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 ags, int *pResOu
9510: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c t);. int (*xFul
9520: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 lPathname)(sqlit
9530: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
9540: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
9550: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 nOut, char *zOut
9560: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c );. void *(*xDl
9570: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 Open)(sqlite3_vf
9580: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
9590: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f zFilename);. vo
95a0: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 id (*xDlError)(s
95b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
95c0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 nByte, char *zE
95d0: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 rrMsg);. void (
95e0: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 *(*xDlSym)(sqlit
95f0: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 e3_vfs*,void*, c
9600: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 onst char *zSymb
9610: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f ol))(void);. vo
9620: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 id (*xDlClose)(s
9630: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 qlite3_vfs*, voi
9640: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 d*);. int (*xRa
9650: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 ndomness)(sqlite
9660: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
9670: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a e, char *zOut);.
9680: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 int (*xSleep)(
9690: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
96a0: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b t microseconds);
96b0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e . int (*xCurren
96c0: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 tTime)(sqlite3_v
96d0: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 fs*, double*);.
96e0: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 int (*xGetLastE
96f0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
9700: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 s*, int, char *)
9710: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 ;. /* New field
9720: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
9730: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 d in figure vers
9740: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 ions. The iVers
9750: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 ion. ** value w
9760: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 ill increment wh
9770: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 enever this happ
9780: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ens. */.};../*.*
9790: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
97a0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 s for the xAcces
97b0: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 s VFS method {H1
97c0: 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 1190} <H11140>.*
97d0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
97e0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e er constants can
97f0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 be used as the
9800: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
9810: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 to.** the xAcces
9820: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b s method of an [
9830: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
9840: 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 ect. {END} They
9850: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
9860: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
9870: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
9880: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
9890: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
98a0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
98b0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
98c0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
98d0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
98e0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
98f0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
9900: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
9910: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
9920: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
9930: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
9940: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 ile is both read
9950: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c able and writabl
9960: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 e..** With SQLIT
9970: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
9980: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
9990: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
99a0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
99b0: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 readable..*/.#de
99c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
99d0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 SS_EXISTS 0.#
99e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
99f0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 CESS_READWRITE 1
9a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9a10: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 ACCESS_READ
9a20: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 2../*.** CAPI3R
9a30: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 EF: Initialize T
9a40: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
9a50: 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 y {H10130} <S200
9a60: 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 00><S30100>.**.*
9a70: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
9a80: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
9a90: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
9aa0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
9ab0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
9ac0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f e3_shutdown() ro
9ad0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 utine.** dealloc
9ae0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 ates any resourc
9af0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c es that were all
9b00: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 ocated by sqlite
9b10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 3_initialize()..
9b20: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
9b30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9b40: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 ze() is an "effe
9b50: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
9b60: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 t is.** the firs
9b70: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
9b80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
9b90: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 nvoked during th
9ba0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a e lifetime of.**
9bb0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 the process, or
9bc0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
9bd0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
9be0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
9bf0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c invoked.** foll
9c00: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 owing a call to
9c10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
9c20: 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 (). Only an eff
9c30: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f ective call.** o
9c40: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 f sqlite3_initia
9c50: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 lize() does any
9c60: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 initialization.
9c70: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 All other calls
9c80: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 .** are harmless
9c90: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 no-ops..**.** A
9ca0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
9cb0: 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 s, sqlite3_initi
9cc0: 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e alize() shall in
9cd0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
9ce0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
9cf0: 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 larly, sqlite3_s
9d00: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 hutdown().** sha
9d10: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
9d20: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
9d30: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
9d40: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
9d50: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
9d60: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
9d70: 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d s..** If for som
9d80: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 e reason, sqlite
9d90: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
9da0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 s unable to init
9db0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 ialize.** the li
9dc0: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 brary (perhaps i
9dd0: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 t is unable to a
9de0: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 llocate a needed
9df0: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a resource such.*
9e00: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 * as a mutex) it
9e10: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 returns an [err
9e20: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 or code] other t
9e30: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e han [SQLITE_OK].
9e40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
9e50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9e60: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
9e70: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
9e80: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 many other.** SQ
9e90: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
9ea0: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 so that an appli
9eb0: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 cation usually d
9ec0: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a oes not need to.
9ed0: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
9ee0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
9ef0: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 irectly. For ex
9f00: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f ample, [sqlite3_
9f10: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 open()].** calls
9f20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9f30: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c ize() so the SQL
9f40: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
9f50: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
9f60: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 y.** initialized
9f70: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f when [sqlite3_o
9f80: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 pen()] is called
9f90: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 if it has not b
9fa0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a e initialized.**
9fb0: 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 already. Howev
9fc0: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 er, if SQLite is
9fd0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
9fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
9ff0: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d AUTOINIT].** com
a000: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
a010: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d , then the autom
a020: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 atic calls to sq
a030: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
a040: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 ().** are omitte
a050: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 d and the applic
a060: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 ation must call
a070: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
a080: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a ze() directly.**
a090: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
a0a0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
a0b0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 interface. For
a0c0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 maximum portabi
a0d0: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 lity,.** it is r
a0e0: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
a0f0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 applications alw
a100: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ays invoke sqlit
a110: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
a120: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f ** directly prio
a130: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f r to using any o
a140: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
a150: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 rface. Future r
a160: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 eleases.** of SQ
a170: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 Lite may require
a180: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 this. In other
a190: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 words, the beha
a1a0: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a vior exhibited.*
a1b0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
a1c0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
a1d0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
a1e0: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f INIT] might beco
a1f0: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c me the.** defaul
a200: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f t behavior in so
a210: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
a220: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a e of SQLite..**.
a230: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
a240: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 s_init() routine
a250: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d does operating-
a260: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a system specific.
a270: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ** initializatio
a280: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 n of the SQLite
a290: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 library. The sq
a2a0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
a2b0: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 * routine undoes
a2c0: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 the effect of s
a2d0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a2e0: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 . Typical tasks
a2f0: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 .** performed by
a300: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
a310: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 include allocati
a320: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 on or deallocati
a330: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 on.** of static
a340: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 resources, initi
a350: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f alization of glo
a360: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a bal variables,.*
a370: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 * setting up a d
a380: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
a390: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 vfs] module, or
a3a0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 setting up.** a
a3b0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
a3c0: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c ation using [sql
a3d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a ite3_config()]..
a3e0: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
a3f0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
a400: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 er invoke either
a410: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
a420: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
a430: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 _os_end() direct
a440: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 ly. The applica
a450: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 tion should only
a460: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
a470: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
a480: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 and sqlite3_shut
a490: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c down(). The sql
a4a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
a4b0: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 * interface is c
a4c0: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 alled automatica
a4d0: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 lly by sqlite3_i
a4e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a nitialize() and.
a4f0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ** sqlite3_os_en
a500: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 d() is called by
a510: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
a520: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 n(). Appropriat
a530: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
a540: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 ions for sqlite3
a550: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
a560: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
a570: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 ** are built int
a580: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 o SQLite when it
a590: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 is compiled for
a5a0: 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 unix, windows,
a5b0: 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e or os/2..** When
a5c0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
a5d0: 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e platforms (usin
a5e0: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 g the [SQLITE_OS
a5f0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c _OTHER=1] compil
a600: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
a610: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f ) the applicatio
a620: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 n must supply a
a630: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 suitable impleme
a640: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 ntation for.** s
a650: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a660: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
a670: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 end(). An appli
a680: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a cation-supplied.
a690: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
a6a0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f n of sqlite3_os_
a6b0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 init() or sqlite
a6c0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 3_os_end().** mu
a6d0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 st return [SQLIT
a6e0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
a6f0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 and some other
a700: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f [error code] upo
a710: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f n.** failure..*/
a720: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 .int sqlite3_ini
a730: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 tialize(void);.i
a740: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nt sqlite3_shutd
a750: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 own(void);.int s
a760: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 qlite3_os_init(v
a770: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
a780: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 3_os_end(void);.
a790: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
a7a0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 Configuring The
a7b0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 SQLite Library
a7c0: 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 {H14100} <S20000
a7d0: 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 ><S30200>.** EXP
a7e0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
a7f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
a800: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
a810: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 s used to make g
a820: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 lobal configurat
a830: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
a840: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 o SQLite in orde
a850: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 r to tune SQLite
a860: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 to the specific
a870: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 needs of.** the
a880: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 application. T
a890: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 he default confi
a8a0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f guration is reco
a8b0: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 mmended for most
a8c0: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
a8d0: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 and so this rou
a8e0: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 tine is usually
a8f0: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 not necessary.
a900: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 It is.** provide
a910: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 d to support rar
a920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 e applications w
a930: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 ith unusual need
a940: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
a950: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
a960: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 terface is not t
a970: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 hreadsafe. The
a980: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d application.** m
a990: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 ust insure that
a9a0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 no other SQLite
a9b0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
a9c0: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a nvoked by other.
a9d0: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 ** threads while
a9e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
a9f0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 ) is running. F
aa00: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 urthermore, sqli
aa10: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 te3_config().**
aa20: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f may only be invo
aa30: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 ked prior to lib
aa40: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 rary initializat
aa50: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
aa60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
aa70: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 ()] or after shu
aa80: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 tdown by [sqlite
aa90: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
aaa0: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c * Note, however,
aab0: 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f that sqlite3_co
aac0: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
aad0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
aae0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
aaf0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
ab00: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
ab10: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
ab20: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
ab30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
ab40: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
ab50: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
ab60: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
ab70: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c G_SINGLETHREAD |
ab80: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
ab90: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
aba0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
abb0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
abc0: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
abd0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
abe0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
abf0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
ac00: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f n the [SQLITE_CO
ac10: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
ac20: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f D | configuratio
ac30: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
ac40: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
ac50: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 nt..**.** When a
ac60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
ac70: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 ption is set, sq
ac80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 lite3_config() r
ac90: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
aca0: 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 K]..** If the op
acb0: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 tion is unknown
acc0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 or SQLite is una
acd0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f ble to set the o
ace0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 ption.** then th
acf0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
ad00: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 ns a non-zero [e
ad10: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
ad20: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
ad30: 0a 2a 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 .** {H14103} A s
ad40: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
ad50: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
ad60: 5f 63 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c _config()] shall
ad70: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
ad80: 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e [SQLITE_OK].
ad90: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 .**.** {H14106}
ada0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e The [sqlite3_con
adb0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
adc0: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 shall return [S
add0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a QLITE_MISUSE].**
ade0: 20 20 20 20 20 20 20 20 20 20 69 66 20 69 74 20 if it
adf0: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 is invoked in be
ae00: 74 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b tween calls to [
ae10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ae20: 7a 65 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 ze()] and.**
ae30: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
ae40: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a hutdown()]..**.*
ae50: 2a 20 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 * {H14120} A suc
ae60: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
ae70: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
ae80: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
ae90: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a SINGLETHREAD]).*
aea0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
aeb0: 20 73 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 set the default
aec0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
aed0: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 ] to Single-thre
aee0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 ad..**.** {H1412
aef0: 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 3} A successful
af00: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
af10: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 _config]([SQLITE
af20: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
af30: 45 41 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 EAD]).**
af40: 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 shall set the
af50: 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 default [threadi
af60: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 ng mode] to Mult
af70: 69 2d 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 i-thread..**.**
af80: 7b 48 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 {H14126} A succe
af90: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
afa0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
afb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
afc0: 52 49 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 RIALIZED]).**
afd0: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 shall set
afe0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 the default [th
aff0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
b000: 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a Serialized..**.
b010: 2a 2a 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 ** {H14129} A su
b020: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
b030: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
b040: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
b050: 5f 4d 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 _MUTEX],X).**
b060: 20 20 20 20 20 20 20 77 68 65 72 65 20 58 20 69 where X i
b070: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
b080: 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 n initialized [s
b090: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
b0a0: 68 6f 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 hods].**
b0b0: 20 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 object shall c
b0c0: 61 75 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 ause all subsequ
b0d0: 65 6e 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 ent mutex operat
b0e0: 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a ions performed.*
b0f0: 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 53 51 * by SQ
b100: 4c 69 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 Lite to use the
b110: 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 mutex methods th
b120: 61 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 at were present
b130: 69 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 in X.**
b140: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c during the call
b150: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b160: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 fig()]..**.** {H
b170: 31 34 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 14132} A success
b180: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
b190: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
b1a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
b1b0: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 UTEX],X).**
b1c0: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20 where X is
b1d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
b1e0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
b1f0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a ethods] object .
b200: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
b210: 6c 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 l overwrite the
b220: 63 6f 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 content of [sqli
b230: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
b240: 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 s] object.**
b250: 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d with the m
b260: 75 74 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 utex methods cur
b270: 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 rently in use by
b280: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b SQLite..**.** {
b290: 48 31 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 H14135} A succes
b2a0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
b2b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b2c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
b2d0: 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 LOC],M).**
b2e0: 20 20 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 where M is a
b2f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
b300: 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 nitialized [sqli
b310: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
b320: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a .** obj
b330: 65 63 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 ect shall cause
b340: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d all subsequent m
b350: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b360: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 operations.**
b370: 20 20 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 performe
b380: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 d by SQLite to u
b390: 73 65 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 se the methods t
b3a0: 68 61 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 hat were present
b3b0: 20 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 in .**
b3c0: 20 4d 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 M during the ca
b3d0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
b3e0: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 onfig()]..**.**
b3f0: 7b 48 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 {H14138} A succe
b400: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
b410: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
b420: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
b430: 54 4d 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 TMALLOC],M).**
b440: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 where M
b450: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
b460: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f an [sqlite3_mem_
b470: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
b480: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 shall.**
b490: 20 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 overwrite the
b4a0: 63 6f 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 content of [sqli
b4b0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
b4c0: 20 6f 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a object with .**
b4d0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 the me
b4e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
b4f0: 6d 65 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c methods currentl
b500: 79 20 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 y in use by.**
b510: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a SQLite..
b520: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 **.** {H14141} A
b530: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
b540: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b550: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
b560: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 FIG_MEMSTATUS],1
b570: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ).** sh
b580: 61 6c 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d all enable the m
b590: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b5a0: 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 status collecti
b5b0: 6f 6e 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 on logic..**.**
b5c0: 7b 48 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 {H14144} A succe
b5d0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
b5e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
b5f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
b600: 4d 53 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 MSTATUS],0).**
b610: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 shall di
b620: 73 61 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 sable the memory
b630: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
b640: 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f us collection lo
b650: 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 gic..**.** {H141
b660: 34 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 47} The memory a
b670: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 llocation status
b680: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 collection logi
b690: 63 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 c shall be.**
b6a0: 20 20 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 enabled b
b6b0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a y default..**.**
b6c0: 20 7b 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 {H14150} A succ
b6d0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
b6e0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
b6f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
b700: 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a CRATCH],S,Z,N).*
b710: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 * where
b720: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e Z and N are non
b730: 2d 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 -negative intege
b740: 72 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 rs and .**
b750: 20 20 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 S is a point
b760: 65 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 er to an aligned
b770: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e memory buffer n
b780: 6f 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 ot less than.**
b790: 20 20 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 Z*N byt
b7a0: 65 73 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c es in size shall
b7b0: 20 63 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 cause S to be u
b7c0: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 sed by the.**
b7d0: 20 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 [scratch
b7e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b7f0: 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 ] for as many as
b800: 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 N simulataneous
b810: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c .** all
b820: 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 ocations each of
b830: 20 73 69 7a 65 20 28 5a 20 26 20 7e 37 29 2e 0a size (Z & ~7)..
b840: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 33 7d 20 41 **.** {H14153} A
b850: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
b860: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b870: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
b880: 46 49 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a FIG_SCRATCH],S,Z
b890: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ,N).**
b8a0: 77 68 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c where S is a NUL
b8b0: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 L pointer shall
b8c0: 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 disable the.**
b8d0: 20 20 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 [scratch
b8e0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
b8f0: 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 r]..**.** {H1415
b900: 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 6} A successful
b910: 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 call to.**
b920: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e [sqlite3_con
b930: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
b940: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 FIG_PAGECACHE],S
b950: 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 ,Z,N).**
b960: 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 where Z and N
b970: 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 are non-negative
b980: 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a integers and .*
b990: 2a 20 20 20 20 20 20 20 20 20 20 53 20 69 73 20 * S is
b9a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
b9b0: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 aligned memory b
b9c0: 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 uffer not less t
b9d0: 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
b9e0: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a Z*N bytes in siz
b9f0: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20 e shall cause S
ba00: 74 6f 20 62 65 20 75 73 65 64 20 62 79 20 74 68 to be used by th
ba10: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
ba20: 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 agecache memory
ba30: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 allocator] for a
ba40: 73 20 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 s many as N simu
ba50: 6c 61 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 lataneous.**
ba60: 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e allocation
ba70: 73 20 65 61 63 68 20 6f 66 20 73 69 7a 65 20 28 s each of size (
ba80: 5a 20 26 20 7e 37 29 2e 0a 2a 2a 0a 2a 2a 20 7b Z & ~7)..**.** {
ba90: 48 31 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 H14159} A succes
baa0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 sful call to.**
bab0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
bac0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
bad0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
bae0: 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 HE],S,Z,N).**
baf0: 20 20 20 20 20 20 20 77 68 65 72 65 20 53 20 69 where S i
bb00: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
bb10: 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 shall disable t
bb20: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
bb30: 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 pagecache memory
bb40: 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a allocator]..**.
bb50: 2a 2a 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 ** {H14162} A su
bb60: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
bb70: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
bb80: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
bb90: 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a _HEAP],H,Z,N).**
bba0: 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 where
bbb0: 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d Z and N are non-
bbc0: 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 negative integer
bbd0: 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 s and .**
bbe0: 20 20 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 H is a pointe
bbf0: 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 r to an aligned
bc00: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f memory buffer no
bc10: 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 t less than.**
bc20: 20 20 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 Z bytes
bc30: 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e in size shall en
bc40: 61 62 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 able the [memsys
bc50: 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 5] memory alloca
bc60: 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 tor.**
bc70: 61 6e 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 and cause it to
bc80: 75 73 65 20 62 75 66 66 65 72 20 53 20 61 73 20 use buffer S as
bc90: 69 74 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 its memory sourc
bca0: 65 20 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 e and to use.**
bcb0: 20 20 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d a minim
bcc0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
bcd0: 7a 65 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b ze of N..**.** {
bce0: 48 31 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 H14165} A succes
bcf0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
bd00: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
bd10: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
bd20: 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 P],H,Z,N).**
bd30: 20 20 20 20 20 20 77 68 65 72 65 20 48 20 69 73 where H is
bd40: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
bd50: 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 shall disable th
bd60: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d e.** [m
bd70: 65 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 emsys5] memory a
bd80: 6c 6c 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 llocator..**.**
bd90: 7b 48 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 {H14168} A succe
bda0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
bdb0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
bdc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
bdd0: 4f 4b 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a OKASIDE],Z,N).**
bde0: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 shall
bdf0: 63 61 75 73 65 20 74 68 65 20 64 65 66 61 75 6c cause the defaul
be00: 74 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d t [lookaside mem
be10: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 ory allocator] c
be20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
be30: 20 20 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 for new
be40: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
be50: 63 74 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 ctions] to be N
be60: 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 slots of Z bytes
be70: 20 65 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 each..*/.SQLITE
be80: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
be90: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 t sqlite3_config
bea0: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a (int, ...);../*.
beb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
bec0: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 figure database
bed0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 connections {H1
bee0: 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 4200} <S20000>.*
bef0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
bf00: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
bf10: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 _db_config() int
bf20: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
bf30: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 o make configura
bf40: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
bf50: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 to a [database c
bf60: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
bf70: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 interface is si
bf80: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c milar to.** [sql
bf90: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 ite3_config()] e
bfa0: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 xcept that the c
bfb0: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 hanges apply to
bfc0: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 a single.** [dat
bfd0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
bfe0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 ] (specified in
bff0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
c000: 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c nt). The.** sql
c010: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
c020: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f interface can o
c030: 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 nly be used imme
c040: 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a diately after.**
c050: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
c060: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 nnection is crea
c070: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
c080: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b e3_open()],.** [
c090: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
c0a0: 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f ], or [sqlite3_o
c0b0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a pen_v2()]. .**.
c0c0: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
c0d0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
c0e0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 3_db_config(D,V,
c0f0: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 ...) is the.**
c100: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
c110: 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 rb - an integer
c120: 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 code that indica
c130: 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 tes what.** aspe
c140: 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 ct of the [datab
c150: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
c160: 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 is being configu
c170: 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 red..** The only
c180: 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 choice for this
c190: 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 value is [SQLIT
c1a0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
c1b0: 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 SIDE]..** New ve
c1c0: 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 rbs are likely t
c1d0: 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 o be added in fu
c1e0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
c1f0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 SQLite..** Addi
c200: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
c210: 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 depend on the v
c220: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 erb..**.** INVAR
c230: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
c240: 34 32 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 4203} A call to
c250: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
c260: 69 67 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 ig(D,V,...)] sha
c270: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
c280: 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 E_OK].**
c290: 20 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 if and only if
c2a0: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 the call is suc
c2b0: 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b cessful..**.** {
c2c0: 48 31 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f H14206} If one o
c2d0: 72 20 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 r more slots of
c2e0: 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d the [lookaside m
c2f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
c300: 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
c310: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
c320: 63 74 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 ction] D are in
c330: 75 73 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c use, then a call
c340: 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
c350: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
c360: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 ig](D,[SQLITE_DB
c370: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
c380: 5d 2c 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 ],...) shall.**
c390: 20 20 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 fail wi
c3a0: 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 th an [SQLITE_BU
c3b0: 53 59 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e SY] return code.
c3c0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 .**.** {H14209}
c3d0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
c3e0: 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 l to .**
c3f0: 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f [sqlite3_db_co
c400: 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f nfig](D,[SQLITE_
c410: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
c420: 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 DE],B,Z,N) where
c430: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 .** D i
c440: 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 s an open [datab
c450: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
c460: 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 and Z and N are
c470: 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 positive.**
c480: 20 20 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e integers an
c490: 64 20 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 d B is an aligne
c4a0: 64 20 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 d buffer at leas
c4b0: 74 20 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 t Z*N bytes in s
c4c0: 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ize.**
c4d0: 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 shall cause the
c4e0: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
c4f0: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 y allocator] for
c500: 20 44 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 D to use buffer
c510: 20 42 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 B .**
c520: 77 69 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 with N slots of
c530: 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a Z bytes each..**
c540: 0a 2a 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 .** {H14212} A s
c550: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
c560: 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b o .** [
c570: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
c580: 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 g](D,[SQLITE_DBC
c590: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
c5a0: 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a ,B,Z,N) where.**
c5b0: 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20 61 D is a
c5c0: 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 n open [database
c5d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
c5e0: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 Z and N are pos
c5f0: 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 itive.**
c600: 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 integers and B
c610: 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
c620: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 shall cause the
c630: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f .** [lo
c640: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
c650: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 llocator] for D
c660: 74 6f 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 to a obtain Z*N
c670: 62 79 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 byte buffer.**
c680: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 from the
c690: 20 70 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 primary memory
c6a0: 61 6c 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 allocator and us
c6b0: 65 20 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a e that buffer.**
c6c0: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 4e with N
c6d0: 20 6c 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 lookaside slots
c6e0: 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 of Z bytes each
c6f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d ..**.** {H14215}
c700: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
c710: 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 ll to .**
c720: 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 [sqlite3_db_c
c730: 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 onfig](D,[SQLITE
c740: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
c750: 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 IDE],B,Z,N) wher
c760: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 e.** D
c770: 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 is an open [data
c780: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
c790: 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 and Z and N are
c7a0: 20 7a 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 zero shall.**
c7b0: 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 disable
c7c0: 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d the [lookaside m
c7d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
c7e0: 20 66 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f for D..**.**.*/
c7f0: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
c800: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
c810: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 _db_config(sqlit
c820: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e e3*, int op, ...
c830: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
c840: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
c850: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b ation Routines {
c860: 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e H10155} <S20120>
c870: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
c880: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
c890: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
c8a0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
c8b0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
c8c0: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
c8d0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
c8e0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
c8f0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
c900: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
c910: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
c920: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
c930: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
c940: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
c950: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
c960: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
c970: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
c980: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
c990: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
c9a0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
c9b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
c9c0: 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 MALLOC]. By cre
c9d0: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
c9e0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
c9f0: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
ca00: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
ca10: 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 onfig()] during
ca20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
ca30: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e n.** application
ca40: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 can specify an
ca50: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f alternative memo
ca60: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
ca70: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 bsystem.** for S
ca80: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 QLite to use for
ca90: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
caa0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
cab0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
cac0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
cad0: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d ith a built-in m
cae0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
caf0: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 that is.** perfe
cb00: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f ctly adequate fo
cb10: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 r the overwhelmi
cb20: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 ng majority of a
cb30: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
cb40: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a nd that this obj
cb50: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 ect is only usef
cb60: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e ul to a tiny min
cb70: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
cb80: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 tions.** with sp
cb90: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 ecialized memory
cba0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
cbb0: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 irements. This
cbc0: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 object is.** als
cbd0: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 o used during te
cbe0: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 sting of SQLite
cbf0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 in order to spec
cc00: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
cc10: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
cc20: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 ocator that simu
cc30: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 lates memory out
cc40: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
cc50: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 tions in.** orde
cc60: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 r to verify that
cc70: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 SQLite recovers
cc80: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d gracefully from
cc90: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 such.** conditi
cca0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ons..**.** The x
ccb0: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 Malloc, xFree, a
ccc0: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 nd xRealloc meth
ccd0: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 ods must work li
cce0: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 ke the.** malloc
ccf0: 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 (), free(), and
cd00: 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 realloc() functi
cd10: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 ons from the sta
cd20: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a ndard library..*
cd30: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c *.** xSize shoul
cd40: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c d return the all
cd50: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 ocated size of a
cd60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
cd70: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 on.** previously
cd80: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 obtained from x
cd90: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c Malloc or xReall
cda0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 oc. The allocat
cdb0: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c ed size.** is al
cdc0: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 ways at least as
cdd0: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 big as the requ
cde0: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d ested size but m
cdf0: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a ay be larger..**
ce00: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 .** The xRoundup
ce10: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
ce20: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 what would be th
ce30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
ce40: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 of.** a memory
ce50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e allocation given
ce60: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
ce70: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d quested size. M
ce80: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ost memory.** al
ce90: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
cea0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 p memory allocat
ceb0: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f ions at least to
cec0: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 the next multip
ced0: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d le.** of 8. Som
cee0: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 e allocators rou
cef0: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 nd up to a large
cf00: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f r multiple or to
cf10: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a a power of 2..*
cf20: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
cf30: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
cf40: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
cf50: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 ocator. (For ex
cf60: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 ample,.** it mig
cf70: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 ht allocate any
cf80: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 require mutexes
cf90: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e or initialize in
cfa0: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 ternal data.** s
cfb0: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 tructures. The
cfc0: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
cfd0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 is invoked (ind
cfe0: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b irectly) by.** [
cff0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d000: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 ()] and should d
d010: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 eallocate any re
d020: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 sources acquired
d030: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 .** by xInit. T
d040: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e he pAppData poin
d050: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 ter is used as t
d060: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
d070: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e r to.** xInit an
d080: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a d xShutdown..*/.
d090: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
d0a0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
d0b0: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
d0c0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
d0d0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
d0e0: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
d0f0: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
d100: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
d110: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
d120: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
d130: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
d140: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
d150: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
d160: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
d170: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
d180: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
d190: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
d1a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
d1b0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
d1c0: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
d1d0: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
d1e0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
d1f0: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
d200: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
d210: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
d220: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
d230: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
d240: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
d250: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
d260: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
d270: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
d280: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
d290: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
d2a0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
d2b0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
d2c0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
d2d0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
d2e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
d2f0: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
d300: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
d310: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
d320: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
d330: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b ration Options {
d340: 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e H10160} <S20000>
d350: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
d360: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
d370: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 stants are the a
d380: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 vailable integer
d390: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
d3a0: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 ptions that.** c
d3b0: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 an be passed as
d3c0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
d3d0: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
d3e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
d3f0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 erface..**.** Ne
d400: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 w configuration
d410: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 options may be a
d420: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
d430: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
d440: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 e..** Existing c
d450: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
d460: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 ions might be di
d470: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 scontinued. App
d480: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
d490: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 uld check the re
d4a0: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b turn code from [
d4b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
d4c0: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
d4d0: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
d4e0: 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 worked. The [sq
d4f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
d500: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 interface will r
d510: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a eturn a.** non-z
d520: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
d530: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
d540: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
d550: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 d configuration
d560: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 option.** is inv
d570: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e oked..**.** <dl>
d580: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d590: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
d5a0: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
d5b0: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
d5c0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
d5d0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 tion. This opti
d5e0: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 on disables.** a
d5f0: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 ll mutexing and
d600: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f puts SQLite into
d610: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 a mode where it
d620: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
d630: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 d.** by a single
d640: 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a thread.</dd>.**
d650: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d660: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
d670: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
d680: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
d690: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
d6a0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f ion. This optio
d6b0: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 n disables.** mu
d6c0: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 texing on [datab
d6d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
d6e0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
d6f0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
d700: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
d710: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 tion is responsi
d720: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a ble for serializ
d730: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a ing access to.**
d740: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
d750: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
d760: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
d770: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 ]. But other mu
d780: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
d790: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c bled so that SQL
d7a0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 ite will be safe
d7b0: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c to use in a mul
d7c0: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 ti-threaded.** e
d7d0: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f nvironment as lo
d7e0: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 ng as no two thr
d7f0: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 eads attempt to
d800: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 use the same.**
d810: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
d820: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d tion] at the sam
d830: 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 e time. See the
d840: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
d850: 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 ].** documentati
d860: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
d870: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f l information.</
d880: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
d890: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
d8a0: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c ALIZED</dt>.** <
d8b0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
d8c0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
d8d0: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 s option. This
d8e0: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a option enables.*
d8f0: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e * all mutexes in
d900: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 cluding the recu
d910: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 rsive.** mutexes
d920: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
d930: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
d940: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
d950: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 t] objects..** I
d960: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 n this mode (whi
d970: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c ch is the defaul
d980: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 t when SQLite is
d990: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
d9a0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
d9b0: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c SAFE=1]) the SQL
d9c0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
d9d0: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a itself serializ
d9e0: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b e access.** to [
d9f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
da00: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
da10: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
da20: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 so that the.** a
da30: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 pplication is fr
da40: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 ee to use the sa
da50: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
da60: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a nection] or the.
da70: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 ** same [prepare
da80: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
da90: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
daa0: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 s at the same ti
dab0: 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b me..** See the [
dac0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
dad0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
dae0: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
daf0: 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a ormation.</dd>.*
db00: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
db10: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 CONFIG_MALLOC</d
db20: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
db30: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
db40: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
db50: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
db60: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
db70: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
db80: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
db90: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
dba0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
dbb0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
dbc0: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f e low-level memo
dbd0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
dbe0: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
dbf0: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a d in place of.**
dc00: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
dc10: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
dc20: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
dc30: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
dc40: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
dc50: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a GETMALLOC</dt>.*
dc60: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
dc70: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
dc80: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
dc90: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
dca0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
dcb0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
dcc0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
dcd0: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c cture. The [sql
dce0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
dcf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
dd00: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
dd10: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
dd20: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ned memory alloc
dd30: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a ation routines..
dd40: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
dd50: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
dd60: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
dd70: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
dd80: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
dd90: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
dda0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 that simulations
ddb0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
ddc0: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a on failure or.**
ddd0: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 tracks memory u
dde0: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c sage, for exampl
ddf0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
de00: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
de10: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a MEMSTATUS</dt>.*
de20: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
de30: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 n takes single a
de40: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
de50: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 int, interpreted
de60: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 as a .** boolea
de70: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 n, which enables
de80: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
de90: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d collection of m
dea0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
deb0: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e .** statistics.
dec0: 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 When disabled,
ded0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 the following SQ
dee0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
def0: 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f become .** non-o
df00: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 perational:.**
df10: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
df20: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
df30: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 used()].** <li
df40: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
df50: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a y_highwater()].*
df60: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
df70: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
df80: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b t()].** <li> [
df90: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
dfa0: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 ].** </ul>.**
dfb0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
dfc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
dfd0: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RATCH</dt>.** <d
dfe0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 d>This option sp
dff0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
e000: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
e010: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
e020: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 se for.** scratc
e030: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 h memory. There
e040: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
e050: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 ents: A pointer
e060: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 to the memory,
e070: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
e080: 61 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 ach scratch buff
e090: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 er (sz), and the
e0a0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 number of buffe
e0b0: 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a rs (N). The sz.
e0c0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 ** argument must
e0d0: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f be a multiple o
e0e0: 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 f 16. The sz par
e0f0: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 ameter should be
e100: 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 a few bytes.**
e110: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
e120: 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 actual scratch s
e130: 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 pace required du
e140: 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 e internal overh
e150: 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 ead..** The firs
e160: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
e170: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
e180: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
e190: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
e1a0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
e1b0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
e1c0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e no more than on
e1d0: 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 e scratch buffer
e1e0: 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 at once per thr
e1f0: 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f ead, so.** N sho
e200: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 uld be set to th
e210: 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d e expected maxim
e220: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 um number of thr
e230: 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a eads. The sz.**
e240: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c parameter shoul
e250: 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 d be 6 times the
e260: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
e270: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
e280: 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 ge size..** Scra
e290: 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 tch buffers are
e2a0: 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 used as part of
e2b0: 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 the btree balanc
e2c0: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 e operation. If
e2d0: 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 .** The btree ba
e2e0: 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 lancer needs add
e2f0: 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 itional memory b
e300: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
e310: 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 ovided by.** scr
e320: 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 atch buffers or
e330: 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 if no scratch bu
e340: 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 ffer space is sp
e350: 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 ecified, then SQ
e360: 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 Lite.** goes to
e370: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
e380: 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 )] to obtain the
e390: 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 memory it needs
e3a0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
e3b0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
e3c0: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a AGECACHE</dt>.**
e3d0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
e3e0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
e3f0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
e400: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 r that SQLite ca
e410: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 n use for.** the
e420: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 database page c
e430: 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 ache with the de
e440: 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 fault page cache
e450: 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 implemenation.
e460: 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 .** This config
e470: 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e uration should n
e480: 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e ot be used if an
e490: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
e4a0: 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 ine page.** cach
e4b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
e4c0: 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 is loaded using
e4d0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
e4e0: 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e IG_PCACHE option
e4f0: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 ..** There are t
e500: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 hree arguments t
e510: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 o this option: A
e520: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
e530: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 ** memory, the s
e540: 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 ize of each page
e550: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e buffer (sz), an
e560: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
e570: 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 pages (N)..** Th
e580: 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 e sz argument mu
e590: 73 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 st be a power of
e5a0: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 two between 512
e5b0: 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 and 32768. The
e5c0: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 first.** argume
e5d0: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 nt should point
e5e0: 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e to an allocation
e5f0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a of at least sz*
e600: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 N bytes of memor
e610: 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c y..** SQLite wil
e620: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 l use the memory
e630: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 provided by the
e640: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
e650: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a to satisfy its.*
e660: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 * memory needs f
e670: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 or the first N p
e680: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 ages that it add
e690: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 s to cache. If
e6a0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 additional.** pa
e6b0: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
e6c0: 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 is needed beyond
e6d0: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 what is provide
e6e0: 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e d by this option
e6f0: 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 , then.** SQLite
e700: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 goes to [sqlite
e710: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 3_malloc()] for
e720: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 the additional s
e730: 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a torage space..**
e740: 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
e750: 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e ion might use on
e760: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 e or more of the
e770: 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f N buffers to ho
e780: 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 ld .** memory ac
e790: 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 counting informa
e7a0: 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a tion. </dd>.**.*
e7b0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
e7c0: 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a FIG_HEAP</dt>.**
e7d0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
e7e0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
e7f0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
e800: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 r that SQLite wi
e810: 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c ll use.** for al
e820: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 l of its dynamic
e830: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
e840: 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 on needs beyond
e850: 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a those provided.*
e860: 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 * for by [SQLITE
e870: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
e880: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e and [SQLITE_CON
e890: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
e8a0: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 ** There are thr
e8b0: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 ee arguments: A
e8c0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
e8d0: 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 emory, the numbe
e8e0: 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e r of.** bytes in
e8f0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 the memory buff
e900: 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 er, and the mini
e910: 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
e920: 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 ize. If.** the
e930: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
e940: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
e950: 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e r) is NULL, then
e960: 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a SQLite reverts.
e970: 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 ** to using its
e980: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 default memory a
e990: 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 llocator (the sy
e9a0: 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d stem malloc() im
e9b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a plementation),.*
e9c0: 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 * undoing any pr
e9d0: 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ior invocation o
e9e0: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
e9f0: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 _MALLOC]. If th
ea00: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e e.** memory poin
ea10: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 ter is not NULL
ea20: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 and either [SQLI
ea30: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
ea40: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 3] or.** [SQLITE
ea50: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d _ENABLE_MEMSYS5]
ea60: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 are defined, th
ea70: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 en the alternati
ea80: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c ve memory.** all
ea90: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 ocator is engage
eaa0: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 d to handle all
eab0: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 of SQLites memor
eac0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
ead0: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ds.</dd>.**.** <
eae0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
eaf0: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c _MUTEX</dt>.** <
eb00: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
eb10: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
eb20: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
eb30: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
eb40: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
eb50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
eb60: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
eb70: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d ture. The argum
eb80: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a ent specifies.**
eb90: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
eba0: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 -level mutex rou
ebb0: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 tines to be used
ebc0: 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 in place.** the
ebd0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 mutex routines
ebe0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
ebf0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
ec00: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
ec10: 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a GETMUTEX</dt>.**
ec20: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
ec30: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
ec40: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
ec50: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
ec60: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
ec70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
ec80: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
ec90: 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 ucture. The.**
eca0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
ecb0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
ecc0: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
ecd0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
ece0: 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 y defined mutex
ecf0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 routines..** Thi
ed00: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
ed10: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
ed20: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 the default mut
ed30: 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ex allocation.**
ed40: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 routines with a
ed50: 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f wrapper used to
ed60: 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 track mutex usa
ed70: 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e ge for performan
ed80: 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 ce.** profiling
ed90: 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 or testing, for
eda0: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a example.</dd>.**
edb0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
edc0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
edd0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
ede0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
edf0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 o arguments that
ee00: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 determine the d
ee10: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 efault.** memory
ee20: 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 allcation looka
ee30: 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f side optimizatio
ee40: 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 n. The first ar
ee50: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
ee60: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
ee70: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
ee80: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f lot and the seco
ee90: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nd is the number
eea0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c of.** slots all
eeb0: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 ocated to each d
eec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
eed0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
eee0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
eef0: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 _PCACHE</dt>.**
ef00: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
ef10: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
ef20: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
ef30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a a pointer to.**
ef40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
ef50: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a che_methods] obj
ef60: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
ef70: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
ef80: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
ef90: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
efa0: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
efb0: 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 on. SQLite make
efc0: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
efd0: 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 ** object and us
efe0: 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 es it for page c
eff0: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ache memory allo
f000: 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a cations.</dd>.**
f010: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
f020: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c ONFIG_GETPCACHE<
f030: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
f040: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
f050: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
f060: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
f070: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c er to an.** [sql
f080: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
f090: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 ods] object. SQ
f0a0: 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 Lite copies of t
f0b0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 he current.** pa
f0c0: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
f0d0: 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 ntation into tha
f0e0: 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a t object.</dd>.*
f0f0: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 *.** </dl>.*/.#d
f100: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
f110: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
f120: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 1 /* nil */.#
f130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
f140: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
f150: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 2 /* nil */.
f160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
f170: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
f180: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 3 /* nil */
f190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f1a0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 CONFIG_MALLOC
f1b0: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 4 /* sqlit
f1c0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 e3_mem_methods*
f1d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f1e0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
f1f0: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c OC 5 /* sql
f200: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
f210: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
f220: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
f230: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 CH 6 /* v
f240: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
f250: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
f260: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
f270: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a ECACHE 7 /*
f280: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
f290: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
f2a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
f2b0: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 EAP 8
f2c0: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 /* void*, int nB
f2d0: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a yte, int min */.
f2e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
f2f0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 ONFIG_MEMSTATUS
f300: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 9 /* boolea
f310: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
f320: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
f330: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 10 /* s
f340: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
f350: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
f360: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
f370: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 ETMUTEX 11
f380: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
f390: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 _methods* */./*
f3a0: 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 previously SQLIT
f3b0: 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c E_CONFIG_CHUNKAL
f3c0: 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 LOC 12 which is
f3d0: 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a now unused. */ .
f3e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
f3f0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
f400: 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 13 /* int in
f410: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
f420: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
f430: 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 E 14 /* s
f440: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
f450: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
f460: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
f470: 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
f480: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
f490: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a he_methods* */..
f4a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
f4b0: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 Configuration Op
f4c0: 74 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c tions {H10170} <
f4d0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20000>.** EXPER
f4e0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
f4f0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
f500: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
f510: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
f520: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
f530: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
f540: 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
f550: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
f560: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
f570: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
f580: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
f590: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
f5a0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
f5b0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
f5c0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
f5d0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
f5e0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
f5f0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
f600: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
f610: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
f620: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
f630: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
f640: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
f650: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
f660: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
f670: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
f680: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
f690: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
f6a0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
f6b0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
f6c0: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
f6d0: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
f6e0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
f6f0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
f700: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
f710: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
f720: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
f730: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 DE</dt>.** <dd>T
f740: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
f750: 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 three additiona
f760: 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 l arguments that
f770: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a determine the .
f780: 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 ** [lookaside me
f790: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 mory allocator]
f7a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
f7b0: 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 r the [database
f7c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
f7d0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
f7e0: 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 nt (the third pa
f7f0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
f800: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
f810: 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 is a.** pointer
f820: 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 to a memory buf
f830: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c fer to use for l
f840: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e ookaside memory.
f850: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 The first.** a
f860: 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e rgument may be N
f870: 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
f880: 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
f890: 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 locate the looka
f8a0: 73 69 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 side.** buffer i
f8b0: 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
f8c0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
f8d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
f8e0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
f8f0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
f900: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
f910: 74 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 t and the third
f920: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
f930: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
f940: 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 ts. The size of
f950: 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 the buffer in t
f960: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
f970: 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 t must be greate
f980: 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 r than.** or equ
f990: 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 al to the produc
f9a0: 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 t of the second
f9b0: 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 and third argume
f9c0: 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 nts.</dd>.**.**
f9d0: 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
f9e0: 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
f9f0: 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 _LOOKASIDE 10
fa00: 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 01 /* void* int
fa10: 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 int */.../*.**
fa20: 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
fa30: 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
fa40: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
fa50: 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 s {H12200} <S107
fa60: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
fa70: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
fa80: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f esult_codes() ro
fa90: 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 utine enables or
faa0: 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a disables the.**
fab0: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
fac0: 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 t codes] feature
fad0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 of SQLite. The
fae0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a extended result.
faf0: 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 ** codes are dis
fb00: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
fb10: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 for historical
fb20: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f compatibility co
fb30: 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a nsiderations..**
fb40: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
fb50: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 **.** {H12201} E
fb60: 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 ach new [databas
fb70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 e connection] sh
fb80: 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 all have the.**
fb90: 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 [extend
fba0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
fbb0: 20 66 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 feature disable
fbc0: 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
fbd0: 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 .** {H12202} The
fbe0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
fbf0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
fc00: 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 D,F)] interface
fc10: 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 shall enable.**
fc20: 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 [extend
fc30: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
fc40: 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 for the [datab
fc50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
fc60: 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 D.** if
fc70: 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 the F parameter
fc80: 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 is true, or dis
fc90: 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 able them if F i
fca0: 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 s false..*/.int
fcb0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
fcc0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 _result_codes(sq
fcd0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 lite3*, int onof
fce0: 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 f);../*.** CAPI3
fcf0: 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 REF: Last Insert
fd00: 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 Rowid {H12220}
fd10: 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 <S10700>.**.** E
fd20: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 ach entry in an
fd30: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 SQLite table has
fd40: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 a unique 64-bit
fd50: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 signed.** integ
fd60: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 er key called th
fd70: 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 e [ROWID | "rowi
fd80: 64 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69 d"]. The rowid i
fd90: 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 s always availab
fda0: 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 le.** as an unde
fdb0: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 clared column na
fdc0: 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 med ROWID, OID,
fdd0: 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f or _ROWID_ as lo
fde0: 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e ng as those.** n
fdf0: 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 ames are not als
fe00: 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 o used by explic
fe10: 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f itly declared co
fe20: 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 lumns. If.** the
fe30: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c table has a col
fe40: 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 umn of type [INT
fe50: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
fe60: 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 ] then that colu
fe70: 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 mn.** is another
fe80: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 alias for the r
fe90: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 owid..**.** This
fea0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
feb0: 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
fec0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a the most recent.
fed0: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 ** successful [I
fee0: 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 NSERT] into the
fef0: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 database from th
ff00: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
ff10: 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 ection].** in th
ff20: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
ff30: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 . If no success
ff40: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a ful [INSERT]s.**
ff50: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 have ever occur
ff60: 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 red on that data
ff70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
ff80: 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 zero is returne
ff90: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b d..**.** If an [
ffa0: 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 INSERT] occurs w
ffb0: 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c ithin a trigger,
ffc0: 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 then the [rowid
ffd0: 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 ] of the inserte
ffe0: 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 d.** row is retu
fff0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 rned by this rou
10000 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 tine as long as
10010 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 the trigger is r
10020 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f unning..** But o
10030 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 nce the trigger
10040 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 terminates, the
10050 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
10060 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a y this routine.*
10070 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 * reverts to the
10080 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 last value inse
10090 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 rted before the
100a0 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a trigger fired..*
100b0 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d *.** An [INSERT]
100c0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 that fails due
100d0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 to a constraint
100e0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 violation is not
100f0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c a.** successful
10100 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f [INSERT] and do
10110 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
10120 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
10130 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 by this.** rout
10140 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 ine. Thus INSER
10150 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 T OR FAIL, INSER
10160 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 T OR IGNORE, INS
10170 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c ERT OR ROLLBACK,
10180 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f .** and INSERT O
10190 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 R ABORT make no
101a0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 changes to the r
101b0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
101c0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 his.** routine w
101d0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 hen their insert
101e0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e ion fails. When
101f0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
10200 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 CE.** encounters
10210 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
10220 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 olation, it does
10230 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a not fail. The.
10240 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e ** INSERT contin
10250 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f ues to completio
10260 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 n after deleting
10270 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 rows that cause
10280 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 d.** the constra
10290 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 int problem so I
102a0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
102b0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 will always cha
102c0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 nge.** the retur
102d0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
102e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
102f0 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 For the purpose
10300 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e s of this routin
10310 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 e, an [INSERT] i
10320 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a s considered to.
10330 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c ** be successful
10340 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 even if it is s
10350 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c ubsequently roll
10360 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 ed back..**.** I
10370 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
10380 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 {H12221} The [s
10390 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
103a0 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 rt_rowid()] func
103b0 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 tion shall retur
103c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
103d0 65 20 5b 72 6f 77 69 64 5d 0a 2a 2a 20 20 20 20 e [rowid].**
103e0 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 of the mos
103f0 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 t recent success
10400 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72 ful [INSERT] per
10410 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 formed on the sa
10420 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b me.** [
10430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
10440 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 ion] and within
10450 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 the same or high
10460 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 er level.**
10470 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e trigger con
10480 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 text, or zero if
10490 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e there have been
104a0 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a no qualifying.*
104b0 2a 20 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45 * [INSE
104c0 52 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a RT] statements..
104d0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 **.** {H12223} T
104e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 he [sqlite3_last
104f0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
10500 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 function shall
10510 72 65 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20 return the.**
10520 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 same valu
10530 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 e when called fr
10540 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 om the same trig
10550 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 ger context.**
10560 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 immediat
10570 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 ely before and a
10580 66 74 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b fter a [ROLLBACK
10590 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 ]..**.** ASSUMPT
105a0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 IONS:.**.** {A12
105b0 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 232} If a separa
105c0 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 te thread perfor
105d0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 ms a new [INSERT
105e0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a ] on the same.**
105f0 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 databa
10600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 se connection wh
10610 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ile the [sqlite3
10620 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
10630 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 id()].**
10640 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 function is ru
10650 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 nning and thus c
10660 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 hanges the last
10670 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a insert [rowid],.
10680 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
10690 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
106a0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
106b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
106c0 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 d()] is.**
106d0 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c unpredictabl
106e0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 e and might not
106f0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 equal either the
10700 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a old or the new.
10710 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 ** last
10720 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e insert [rowid].
10730 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
10740 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
10750 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
10760 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
10770 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
10780 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
10790 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 Modified {H1224
107a0 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S10600>.**.*
107b0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
107c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
107d0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 er of database r
107e0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 ows that were ch
107f0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 anged.** or inse
10800 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 rted or deleted
10810 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 by the most rece
10820 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 ntly completed S
10830 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL statement.**
10840 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
10850 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
10860 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 cified by the fi
10870 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a rst parameter..*
10880 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 * Only changes t
10890 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 hat are directly
108a0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
108b0 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 e [INSERT], [UPD
108c0 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c ATE],.** or [DEL
108d0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ETE] statement a
108e0 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 re counted. Aux
108f0 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 iliary changes c
10900 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 aused by.** trig
10910 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 gers are not cou
10920 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 nted. Use the [s
10930 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
10940 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e nges()] function
10950 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 .** to find the
10960 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 total number of
10970 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e changes includin
10980 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 g changes caused
10990 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a by triggers..**
109a0 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 .** A "row chang
109b0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 e" is a change t
109c0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f o a single row o
109d0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 f a single table
109e0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e .** caused by an
109f0 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c INSERT, DELETE,
10a00 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 or UPDATE state
10a10 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 ment. Rows that
10a20 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 .** are changed
10a30 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 as side effects
10a40 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 of REPLACE const
10a50 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
10a60 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 ,.** rollback, A
10a70 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
10a80 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 DROP TABLE, or
10a90 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
10aa0 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
10ab0 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
10ac0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a t row changes..*
10ad0 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 *.** A "trigger
10ae0 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 context" is a sc
10af0 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e ope of execution
10b00 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 that begins and
10b10 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 .** ends with th
10b20 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 e script of a tr
10b30 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c igger. Most SQL
10b40 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a statements are.
10b50 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 ** evaluated out
10b60 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 side of any trig
10b70 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 ger. This is th
10b80 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a e "top level".**
10b90 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
10ba0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 . If a trigger
10bb0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 fires from the t
10bc0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e op level, a.** n
10bd0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
10be0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f xt is entered fo
10bf0 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f r the duration o
10c00 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 f that one.** tr
10c10 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 igger. Subtrigg
10c20 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f ers create subco
10c30 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 ntexts for their
10c40 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a duration..**.**
10c50 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 Calling [sqlite
10c60 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 3_exec()] or [sq
10c70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
10c80 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a cursively does.*
10c90 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e * not create a n
10ca0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
10cb0 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 xt..**.** This f
10cc0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
10cd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 the number of di
10ce0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 rect row changes
10cf0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 in the.** most
10d00 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 recent INSERT, U
10d10 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
10d20 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
10d30 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 n the same.** tr
10d40 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a igger context..*
10d50 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 *.** Thus, when
10d60 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
10d70 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 top level, this
10d80 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
10d90 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
10da0 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 f changes in the
10db0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
10dc0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
10dd0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 DELETE.** that a
10de0 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 lso occurred at
10df0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 the top level.
10e00 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 Within the body
10e10 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a of a trigger,.**
10e20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
10e30 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 nges() interface
10e40 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 can be called t
10e50 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
10e60 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 r of.** changes
10e70 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
10e80 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 ntly completed I
10e90 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
10ea0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 r DELETE.** stat
10eb0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
10ec0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d body of the sam
10ed0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f e trigger..** Ho
10ee0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 wever, the numbe
10ef0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 r returned does
10f00 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e not include chan
10f10 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 ges.** caused by
10f20 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e subtriggers sin
10f30 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 ce those have th
10f40 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e eir own context.
10f50 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d .**.** SQLite im
10f60 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d plements the com
10f70 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f mand "DELETE FRO
10f80 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 M table" without
10f90 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a a WHERE clause.
10fa0 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 ** by dropping a
10fb0 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 nd recreating th
10fc0 65 20 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 e table. Doing
10fd0 73 6f 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 so is much faste
10fe0 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 r than going.**
10ff0 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 through and dele
11000 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 ting individual
11010 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 elements from th
11020 65 20 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 e table. Becaus
11030 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 e of this.** opt
11040 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 imization, the d
11050 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c eletions in "DEL
11060 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 ETE FROM table"
11070 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e are not row chan
11080 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 ges and.** will
11090 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 not be counted b
110a0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 y the sqlite3_ch
110b0 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 anges() or [sqli
110c0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
110d0 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e s()].** function
110e0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 s, regardless of
110f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
11100 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 lements that wer
11110 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 e originally.**
11120 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 in the table. T
11130 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 o get an accurat
11140 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e e count of the n
11150 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 umber of rows de
11160 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 leted, use.** "D
11170 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
11180 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 WHERE 1" instea
11190 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 d. Or recompile
111a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 using the.** [S
111b0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 QLITE_OMIT_TRUNC
111c0 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e ATE_OPTIMIZATION
111d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
111e0 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 ption to disable
111f0 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 the.** optimiza
11200 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 tion on all quer
11210 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ies..**.** INVAR
11220 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
11230 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2241} The [sqlit
11240 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 e3_changes()] fu
11250 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 nction shall ret
11260 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
11270 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f f.** ro
11280 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 w changes caused
11290 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
112a0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ent INSERT, UPDA
112b0 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 TE,.**
112c0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
112d0 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ent on the same
112e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
112f0 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ion and.**
11300 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 within the s
11310 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 ame or higher tr
11320 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f igger context, o
11330 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 r zero if there
11340 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 have.**
11350 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 not been any qu
11360 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 alifying row cha
11370 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 nges..**.** {H12
11380 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 243} Statements
11390 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c of the form "DEL
113a0 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 ETE FROM tablena
113b0 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 me" with no.**
113c0 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c WHERE cl
113d0 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 ause shall cause
113e0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
113f0 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 s to.**
11400 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
11410 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a s()] to return z
11420 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 ero, regardless
11430 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
11440 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 number of row
11450 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 s originally in
11460 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a the table..**.**
11470 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
11480 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 .** {A12252} If
11490 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
114a0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
114b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
114c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
114d0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c ** whil
114e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
114f0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
11500 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
11510 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 returned.**
11520 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 is unpredic
11530 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
11540 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 aningful..*/.int
11550 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
11560 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
11570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
11580 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
11590 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 s Modified {H122
115a0 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 60} <S10600>.**.
115b0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
115c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
115d0 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 ber of row chang
115e0 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 es caused by INS
115f0 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f ERT,.** UPDATE o
11600 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
11610 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 nts since the [d
11620 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11630 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a on] was opened..
11640 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 ** The count inc
11650 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 ludes all change
11660 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 s from all trigg
11670 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f er contexts. Ho
11680 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f wever,.** the co
11690 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
116a0 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 lude changes use
116b0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 d to implement R
116c0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e EPLACE constrain
116d0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 ts,.** do rollba
116e0 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f cks or ABORT pro
116f0 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 cessing, or DROP
11700 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e table processin
11710 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 g..** The change
11720 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 s are counted as
11730 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 soon as the sta
11740 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
11750 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d s them is.** com
11760 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 pleted (when the
11770 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c statement handl
11780 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b e is passed to [
11790 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
117a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
117b0 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a finalize()])..**
117c0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 .** SQLite imple
117d0 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e ments the comman
117e0 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 d "DELETE FROM t
117f0 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 able" without a
11800 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 WHERE clause.**
11810 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 by dropping and
11820 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 recreating the t
11830 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 able. (This is
11840 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e much faster than
11850 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 going.** throug
11860 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 h and deleting i
11870 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e ndividual elemen
11880 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c ts from the tabl
11890 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 e.) Because of
118a0 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 this.** optimiza
118b0 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 tion, the deleti
118c0 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 ons in "DELETE F
118d0 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e ROM table" are n
118e0 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 ot row changes a
118f0 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 nd.** will not b
11900 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 e counted by the
11910 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
11920 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 () or [sqlite3_t
11930 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a otal_changes()].
11940 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 ** functions, re
11950 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
11960 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e number of elemen
11970 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 ts that were ori
11980 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 ginally.** in th
11990 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 e table. To get
119a0 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 an accurate cou
119b0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 nt of the number
119c0 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 of rows deleted
119d0 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 , use.** "DELETE
119e0 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 FROM table WHER
119f0 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20 E 1" instead.
11a00 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 Or recompile usi
11a10 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ng the.** [SQLIT
11a20 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f E_OMIT_TRUNCATE_
11a30 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f OPTIMIZATION] co
11a40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
11a50 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 n to disable the
11a60 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e .** optimization
11a70 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e on all queries.
11a80 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
11a90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
11aa0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
11ab0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 e..**.** INVARIA
11ac0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 NTS:.**.** {H122
11ad0 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 61} The [sqlite3
11ae0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
11af0 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f ] returns the to
11b00 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 tal number.**
11b10 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 of row ch
11b20 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
11b30 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
11b40 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a and/or DELETE.**
11b50 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d statem
11b60 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 ents on the same
11b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11b80 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a ction], in any.*
11b90 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 * trigg
11ba0 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 er context, sinc
11bb0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
11bc0 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 onnection was cr
11bd0 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 eated..**.** {H1
11be0 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 2263} Statements
11bf0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 of the form "DE
11c00 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e LETE FROM tablen
11c10 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 ame" with no.**
11c20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 WHERE c
11c30 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 lause shall not
11c40 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
11c50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 returned.**
11c60 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 by [sqlite
11c70 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
11c80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 )]..**.** ASSUMP
11c90 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 TIONS:.**.** {A1
11ca0 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 2264} If a separ
11cb0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 ate thread makes
11cc0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 changes on the
11cd0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
11ce0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 nnection.**
11cf0 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 while [sqli
11d00 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
11d10 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
11d20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a then the value.*
11d30 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
11d40 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 ned is unpredict
11d50 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
11d60 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 ningful..*/.int
11d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
11d80 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
11d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
11da0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
11db0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
11dc0 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 {H12270} <S3050
11dd0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0>.**.** This fu
11de0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e nction causes an
11df0 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 y pending databa
11e00 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 se operation to
11e10 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 abort and.** ret
11e20 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 urn at its earli
11e30 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e est opportunity.
11e40 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
11e50 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 typically.** ca
11e60 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 lled in response
11e70 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f to a user actio
11e80 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 n such as pressi
11e90 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f ng "Cancel".** o
11ea0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 r Ctrl-C where t
11eb0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 he user wants a
11ec0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 long query opera
11ed0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 tion to halt.**
11ee0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a immediately..**.
11ef0 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f ** It is safe to
11f00 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
11f10 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 ne from a thread
11f20 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
11f30 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 the.** thread th
11f40 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 at is currently
11f50 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 running the data
11f60 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 base operation.
11f70 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f But it.** is no
11f80 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 t safe to call t
11f90 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
11fa0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
11fb0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a nection] that.**
11fc0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 is closed or mi
11fd0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 ght close before
11fe0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
11ff0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
12000 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 .** If an SQL op
12010 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 eration is very
12020 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 nearly finished
12030 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
12040 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 .** sqlite3_inte
12050 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 rrupt() is calle
12060 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 d, then it might
12070 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 not have an opp
12080 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 ortunity.** to b
12090 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e e interrupted an
120a0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 d might continue
120b0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
120c0 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 **.** An SQL ope
120d0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 ration that is i
120e0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 nterrupted will
120f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 return [SQLITE_I
12100 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 NTERRUPT]..** If
12110 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 the interrupted
12120 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
12130 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 s an INSERT, UPD
12140 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
12150 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 * that is inside
12160 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
12170 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 nsaction, then t
12180 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 he entire transa
12190 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 ction.** will be
121a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
121b0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a omatically..**.*
121c0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
121d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
121e0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e has no effect on
121f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
12200 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
12210 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 ted after sqlite
12220 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
12230 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 turns..**.** INV
12240 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
12250 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c H12271} The [sql
12260 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
12270 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
12280 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 force all runni
12290 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 ng.** S
122a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 QL statements as
122b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
122c0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
122d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 connection.**
122e0 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 to halt a
122f0 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 fter processing
12300 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 at most one addi
12310 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 tional row of da
12320 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 ta..**.** {H1227
12330 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 2} Any SQL state
12340 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 ment that is int
12350 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c errupted by [sql
12360 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
12370 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 ].** wi
12380 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
12390 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a E_INTERRUPT]..**
123a0 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a .** ASSUMPTIONS:
123b0 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 .**.** {A12279}
123c0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
123d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
123e0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 s while [sqlite3
123f0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a _interrupt()].**
12400 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e is run
12410 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 ning then bad th
12420 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 ings will likely
12430 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 happen..*/.void
12440 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
12450 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f pt(sqlite3*);../
12460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
12470 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
12480 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 QL Statement Is
12490 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 Complete {H10510
124a0 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S70200>.**.**
124b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
124c0 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 are useful for c
124d0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
124e0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
124f0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
12500 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
12510 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f seems to form co
12520 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 mplete a SQL sta
12530 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
12540 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
12550 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
12560 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
12570 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
12580 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
12590 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
125a0 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 eturn true if th
125b0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a e input string.*
125c0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 * appears to be
125d0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
125e0 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 tatement. A sta
125f0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 tement is judged
12600 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 to be.** comple
12610 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 te if it ends wi
12620 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 th a semicolon t
12630 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 oken and is not
12640 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a a fragment of a.
12650 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 ** CREATE TRIGGE
12660 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 R statement. Se
12670 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 micolons that ar
12680 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 e embedded withi
12690 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 n.** string lite
126a0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 rals or quoted i
126b0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 dentifier names
126c0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 or comments are
126d0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 not.** independe
126e0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 nt tokens (they
126f0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 are part of the
12700 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 token in which t
12710 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 hey are.** embed
12720 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f ded) and thus do
12730 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 not count as a
12740 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e statement termin
12750 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ator..**.** Thes
12760 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f e routines do no
12770 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 t parse the SQL
12780 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a statements thus.
12790 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 ** will not dete
127a0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 ct syntactically
127b0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a incorrect SQL..
127c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
127d0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d :.**.** {H10511}
127e0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 A successful ev
127f0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c aluation of [sql
12800 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d ite3_complete()]
12810 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
12820 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
12830 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 e16()] functions
12840 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 shall.**
12850 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 return a nume
12860 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c ric 1 if and onl
12870 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f y if the last no
12880 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 n-whitespace.**
12890 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 token i
128a0 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 n their input is
128b0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 a semicolon tha
128c0 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 t is not in betw
128d0 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 een.**
128e0 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e the BEGIN and EN
128f0 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 D of a CREATE TR
12900 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e IGGER statement.
12910 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 .**.** {H10512}
12920 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f If a memory allo
12930 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 cation error occ
12940 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e urs during an in
12950 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 vocation.**
12960 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 of [sqlite3
12970 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 _complete()] or
12980 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
12990 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a e16()] then the.
129a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 ** rout
129b0 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ine shall return
129c0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
129d0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f .**.** ASSUMPTIO
129e0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 NS:.**.** {A1051
129f0 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 2} The input to
12a00 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
12a10 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
12a20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
12a30 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 * UTF-8
12a40 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
12a50 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 A10513} The inpu
12a60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
12a70 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 mplete16()] must
12a80 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
12a90 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 nated.**
12aa0 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 UTF-16 string
12ab0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
12ac0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c rder..*/.int sql
12ad0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
12ae0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
12af0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
12b00 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 lete16(const voi
12b10 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d *sql);../*.**
12b20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 CAPI3REF: Regist
12b30 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f er A Callback To
12b40 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 Handle SQLITE_B
12b50 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 USY Errors {H123
12b60 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 10} <S40400>.**.
12b70 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
12b80 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
12b90 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 function that mi
12ba0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
12bb0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
12bc0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
12bd0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 open a database
12be0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 table that anot
12bf0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
12c00 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 process has loc
12c10 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ked..**.** If th
12c20 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
12c30 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 is NULL, then [S
12c40 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
12c50 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
12c60 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 CKED].** is retu
12c70 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 rned immediately
12c80 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 upon encounteri
12c90 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 ng the lock. If
12ca0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
12cb0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c k.** is not NULL
12cc0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 , then the callb
12cd0 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f ack will be invo
12ce0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 ked with two arg
12cf0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 uments..**.** Th
12d00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
12d10 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 to the handler
12d20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
12d30 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 void* pointer w
12d40 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 hich.** is the t
12d50 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
12d60 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
12d70 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 ndler(). The se
12d80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
12d90 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
12da0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
12db0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
12dc0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
12dd0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
12de0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 n invoked for th
12df0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 is locking event
12e00 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 . If the.** bus
12e10 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
12e20 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
12e30 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
12e40 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
12e50 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
12e60 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
12e70 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
12e80 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
12e90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
12ea0 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b If the callback
12eb0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
12ec0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 o, then another
12ed0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 attempt.** is ma
12ee0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 de to open the d
12ef0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 atabase for read
12f00 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c ing and the cycl
12f10 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a e repeats..**.**
12f20 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 The presence of
12f30 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
12f40 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 does not guarant
12f50 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 ee that it will
12f60 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 be invoked.** wh
12f70 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b en there is lock
12f80 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 contention. If
12f90 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
12fa0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 s that invoking
12fb0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 the busy.** hand
12fc0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
12fd0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 in a deadlock,
12fe0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 it will go ahead
12ff0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
13000 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 ITE_BUSY].** or
13010 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
13020 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f OCKED] instead o
13030 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 f invoking the b
13040 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 usy handler..**
13050 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 Consider a scena
13060 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 rio where one pr
13070 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 ocess is holding
13080 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 a read lock tha
13090 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e t.** it is tryin
130a0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 g to promote to
130b0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
130c0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 and.** a second
130d0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
130e0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f ng a reserved lo
130f0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 ck that it is tr
13100 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f ying.** to promo
13110 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 te to an exclusi
13120 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 ve lock. The fi
13130 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e rst process cann
13140 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 ot proceed.** be
13150 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
13160 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e ked by the secon
13170 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 d and the second
13180 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a process cannot.
13190 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 ** proceed becau
131a0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
131b0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 by the first.
131c0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 If both processe
131d0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 s.** invoke the
131e0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e busy handlers, n
131f0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 either will make
13200 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 any progress.
13210 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 Therefore,.** SQ
13220 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 Lite returns [SQ
13230 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 LITE_BUSY] for t
13240 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
13250 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 , hoping that th
13260 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 is.** will induc
13270 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 e the first proc
13280 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 ess to release i
13290 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 ts read lock and
132a0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 allow.** the se
132b0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 cond process to
132c0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 proceed..**.** T
132d0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
132e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
132f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
13300 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 ITE_BUSY] error
13310 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 is converted to
13320 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
13330 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 OCKED].** when S
13340 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 QLite is in the
13350 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 middle of a larg
13360 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 e transaction wh
13370 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 ere all the.** c
13380 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 hanges will not
13390 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d fit into the in-
133a0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 memory cache. S
133b0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c QLite will.** al
133c0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 ready hold a RES
133d0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 ERVED lock on th
133e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c e database file,
133f0 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a but it needs.**
13400 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 to promote this
13410 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 lock to EXCLUSI
13420 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 VE so that it ca
13430 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a n spill cache.**
13440 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 pages into the
13450 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
13460 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f thout harm to co
13470 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 ncurrent.** read
13480 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 ers. If it is u
13490 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 nable to promote
134a0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 the lock, then
134b0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a the in-memory.**
134c0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c cache will be l
134d0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 eft in an incons
134e0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 istent state and
134f0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a so the error.**
13500 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 code is promote
13510 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 d from the relat
13520 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 ively benign [SQ
13530 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a LITE_BUSY] to.**
13540 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 the more severe
13550 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
13560 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 LOCKED]. This e
13570 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 rror code promot
13580 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e ion.** forces an
13590 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 automatic rollb
135a0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 ack of the chang
135b0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 es. See the.**
135c0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 <a href="/cvstra
135d0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 c/wiki?p=Corrupt
135e0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 ionFollowingBusy
135f0 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 Error">.** Corru
13600 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
13610 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 syError</a> wiki
13620 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 page for a disc
13630 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a ussion of why.**
13640 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 this is importa
13650 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 nt..**.** There
13660 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
13670 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
13680 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 r defined for ea
13690 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ch.** [database
136a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 connection]. Se
136b0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 tting a new busy
136c0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 handler clears
136d0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c any.** previousl
136e0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 y set handler.
136f0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
13700 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
13710 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
13720 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
13730 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
13740 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
13750 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
13760 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
13770 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
13780 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
13790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
137a0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
137b0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
137c0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
137d0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
137e0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
137f0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 ior..** .** INVA
13800 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
13810 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 12311} The [sqli
13820 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
13830 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f (D,C,A)] functio
13840 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a n shall replace.
13850 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79 ** busy
13860 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 callback in the
13870 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13880 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 ction] D with a
13890 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
138a0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
138b0 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 er C and applica
138c0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
138d0 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 r A..**.** {H123
138e0 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 12} Newly create
138f0 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e d [database conn
13900 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 ections] shall h
13910 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 ave a busy.**
13920 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f handler o
13930 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 f NULL..**.** {H
13940 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 12314} When two
13950 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 or more [databas
13960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 e connections] s
13970 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 hare a.**
13980 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 [sqlite3_enab
13990 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 le_shared_cache
139a0 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c | common cache],
139b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
139c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f busy handler fo
139d0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 r the database c
139e0 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e onnection curren
139f0 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 tly using.**
13a00 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20 the cache
13a10 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 shall be invoked
13a20 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 when the cache
13a30 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 encounters a loc
13a40 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 k..**.** {H12316
13a50 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 } If a busy hand
13a60 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ler callback ret
13a70 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 urns zero, then
13a80 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 the SQLite inter
13a90 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 face.**
13aa0 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 that provoked t
13ab0 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 he locking event
13ac0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 shall return [S
13ad0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a QLITE_BUSY]..**.
13ae0 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 ** {H12318} SQLi
13af0 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 te shall invokes
13b00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
13b10 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d r with two argum
13b20 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 ents which.**
13b30 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 are a cop
13b40 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 y of the pointer
13b50 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 supplied by the
13b60 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
13b70 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
13b80 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
13b90 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 ler()] and a cou
13ba0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 nt of the number
13bb0 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 of prior.**
13bc0 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e invocation
13bd0 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 s of the busy ha
13be0 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 ndler for the sa
13bf0 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 me locking event
13c00 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 ..**.** ASSUMPTI
13c10 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 ONS:.**.** {A123
13c20 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 19} A busy handl
13c30 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 er must not clos
13c40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
13c50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 onnection.**
13c60 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 or [prepar
13c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
13c80 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
13c90 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a usy handler..*/.
13ca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
13cb0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
13cc0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
13cd0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
13ce0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
13cf0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
13d00 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 t {H12340} <S404
13d10 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 10>.**.** This r
13d20 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 outine sets a [s
13d30 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
13d40 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c ler | busy handl
13d50 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a er] that sleeps.
13d60 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 ** for a specifi
13d70 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d ed amount of tim
13d80 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 e when a table i
13d90 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 s locked. The h
13da0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
13db0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
13dc0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
13dd0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
13de0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
13df0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
13e00 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 ated. {H12343} A
13e10 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 fter "ms" millis
13e20 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
13e30 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
13e40 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
13e50 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
13e60 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
13e70 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
13e80 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
13e90 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
13ea0 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 .**.** Calling t
13eb0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
13ec0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
13ed0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
13ee0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
13ef0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
13f00 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ndlers..**.** Th
13f10 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
13f20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
13f30 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
13f40 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
13f50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
13f60 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
13f70 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
13f80 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
13f90 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
13fa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
13fb0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
13fc0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
13fd0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
13fe0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
13ff0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
14000 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ared..**.** INVA
14010 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
14020 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 12341} The [sqli
14030 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
14040 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 ()] function sha
14050 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 ll override any
14060 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 prior.**
14070 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f [sqlite3_busy_
14080 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 timeout()] or [s
14090 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
140a0 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a ler()] setting.*
140b0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 * on th
140c0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
140d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
140e0 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 .** {H12343} If
140f0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
14100 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 r to [sqlite3_bu
14110 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 sy_timeout()] is
14120 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 less than.**
14130 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 or equal
14140 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 to zero, then th
14150 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 e busy handler s
14160 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 hall be cleared
14170 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 so that.**
14180 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 all subseque
14190 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 nt locking event
141a0 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 s immediately re
141b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
141c0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 Y]..**.** {H1234
141d0 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 4} If the 2nd pa
141e0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
141f0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
14200 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 ()] is a positiv
14210 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 e.** nu
14220 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 mber N, then a b
14230 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c usy handler shal
14240 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65 l be set that re
14250 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a peatedly calls.*
14260 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78 * the x
14270 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 Sleep() method i
14280 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 n the [sqlite3_v
14290 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 fs | VFS interfa
142a0 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 ce] until.**
142b0 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65 either the
142c0 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 lock clears or
142d0 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 until the cumula
142e0 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a tive sleep time.
142f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f ** repo
14300 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c rted back by xSl
14310 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 eep() exceeds N
14320 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f milliseconds..*/
14330 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
14340 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 y_timeout(sqlite
14350 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 3*, int ms);../*
14360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
14370 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e nvenience Routin
14380 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 es For Running Q
14390 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 ueries {H12370}
143a0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 <S10000>.**.** D
143b0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e efinition: A <b>
143c0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e result table</b>
143d0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 is memory data
143e0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 structure create
143f0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d by the.** [sql
14400 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
14410 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 ] interface. A
14420 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 result table rec
14430 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ords the.** comp
14440 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c lete query resul
14450 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d ts from one or m
14460 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a ore queries..**.
14470 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e ** The table con
14480 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 ceptually has a
14490 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 number of rows a
144a0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 nd columns. But
144b0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 .** these number
144c0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f s are not part o
144d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
144e0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 le itself. Thes
144f0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 e.** numbers are
14500 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 obtained separa
14510 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 tely. Let N be
14520 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
14530 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 ws.** and M be t
14540 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
14550 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 umns..**.** A re
14560 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e sult table is an
14570 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
14580 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 rs to zero-termi
14590 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
145a0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ngs..** There ar
145b0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e e (N+1)*M elemen
145c0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e ts in the array.
145d0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f The first M po
145e0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 inters point.**
145f0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
14600 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
14610 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d contain the nam
14620 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
14630 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e s..** The remain
14640 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 ing entries all
14650 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 point to query r
14660 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 esults. NULL va
14670 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 lues result.** i
14680 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e n NULL pointers.
14690 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 All other valu
146a0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 es are in their
146b0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
146c0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
146d0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 representation a
146e0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
146f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
14700 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 xt()]..**.** A r
14710 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 esult table migh
14720 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 t consist of one
14730 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 or more memory
14740 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 allocations..**
14750 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
14760 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 o pass a result
14770 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 table directly t
14780 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
14790 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 )]..** A result
147a0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 table should be
147b0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e deallocated usin
147c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f g [sqlite3_free_
147d0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
147e0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 As an example of
147f0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
14800 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 e format, suppos
14810 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 e a query result
14820 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 .** is as follow
14830 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
14840 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
14850 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 Name
14860 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 | Age.**
14870 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------------
14880 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 --------.**
14890 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c Alice |
148a0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 43.** Bo
148b0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a b | 28.*
148c0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 * Cindy
148d0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 | 21.** </p
148e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
148f0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 .**.** There are
14900 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d two column (M==
14910 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 2) and three row
14920 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 s (N==3). Thus
14930 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 the.** result ta
14940 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 ble has 8 entrie
14950 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 s. Suppose the
14960 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
14970 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 stored.** in an
14980 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 array names azRe
14990 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 sult. Then azRe
149a0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 sult holds this
149b0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c content:.**.** <
149c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
149d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
149e0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 ult[0] = "Na
149f0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 me";.** a
14a00 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d zResult[1] =
14a10 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Age";.**
14a20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 azResult[2
14a30 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 ] = "Alice";.**
14a40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
14a50 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a #91;3] = "43";.*
14a60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
14a70 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 t[4] = "Bob"
14a80 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
14a90 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 sult[5] = "2
14aa0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 8";.** az
14ab0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 Result[6] =
14ac0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 "Cindy";.**
14ad0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
14ae0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 7] = "21";.** </
14af0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
14b00 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
14b10 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
14b20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 function evaluat
14b30 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a es one or more.*
14b40 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 * semicolon-sepa
14b50 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d rated SQL statem
14b60 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f ents in the zero
14b70 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
14b80 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 8.** string of i
14b90 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ts 2nd parameter
14ba0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 . It returns a
14bb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
14bc0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
14bd0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
14be0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
14bf0 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 After the calli
14c00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 ng function has
14c10 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
14c20 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 he result, it sh
14c30 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 ould.** pass the
14c40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
14c50 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
14c60 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
14c70 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f le() in order to
14c80 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 .** release the
14c90 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 memory that was
14ca0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 malloced. Becau
14cb0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 se of the way th
14cc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e.** [sqlite3_ma
14cd0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 lloc()] happens
14ce0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 within sqlite3_g
14cf0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 et_table(), the
14d00 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 calling.** funct
14d10 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 ion must not try
14d20 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 to call [sqlite
14d30 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 3_free()] direct
14d40 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 ly. Only.** [sq
14d50 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
14d60 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 ()] is able to r
14d70 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
14d80 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 y properly and s
14d90 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 afely..**.** The
14da0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
14db0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 le() interface i
14dc0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 s implemented as
14dd0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e a wrapper aroun
14de0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 d.** [sqlite3_ex
14df0 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 ec()]. The sqli
14e00 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
14e10 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 routine does not
14e20 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 have access.**
14e30 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 to any internal
14e40 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
14e50 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 of SQLite. It u
14e60 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 ses only the pub
14e70 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 lic.** interface
14e80 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 defined here.
14e90 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 As a consequence
14ea0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 , errors that oc
14eb0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 cur in the.** wr
14ec0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 apper layer outs
14ed0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 ide of the inter
14ee0 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 nal [sqlite3_exe
14ef0 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f c()] call are no
14f00 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 t.** reflected i
14f10 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
14f20 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
14f30 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 rrcode()] or [sq
14f40 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
14f50 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
14f60 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 S:.**.** {H12371
14f70 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f } If a [sqlite3_
14f80 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 get_table()] fai
14f90 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ls a memory allo
14fa0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 cation, then.**
14fb0 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c it shal
14fc0 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c l free the resul
14fd0 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f t table under co
14fe0 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 nstruction, abor
14ff0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 t the.**
15000 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 query in proce
15010 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 ss, skip any sub
15020 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c sequent queries,
15030 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 set the.**
15040 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 *pazResult
15050 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 output pointer t
15060 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 o NULL and retur
15070 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
15080 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d ..**.** {H12373}
15090 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e If the pnColumn
150a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
150b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
150c0 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a ()] is not NULL.
150d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
150e0 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e a successful in
150f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
15100 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
15110 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 ] shall.**
15120 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 write the nu
15130 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
15140 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 in the.**
15150 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 result set of
15160 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 the query into
15170 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a *pnColumn..**.**
15180 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 {H12374} If the
15190 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 pnRow parameter
151a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 to [sqlite3_get
151b0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 _table()] is not
151c0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 NULL.**
151d0 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 then a success
151e0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ful invocation o
151f0 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 f [sqlite3_get_t
15200 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a able()] shall.**
15210 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73 writes
15220 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
15230 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 ows in the.**
15240 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 result se
15250 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 t of the query i
15260 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a nto *pnRow..**.*
15270 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 * {H12376} A suc
15280 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
15290 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 on of [sqlite3_g
152a0 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 et_table()] that
152b0 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 computes.**
152c0 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 N rows of
152d0 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f result with C co
152e0 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 lumns per row sh
152f0 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 all make *pazRes
15300 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ult.**
15310 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 point to an arra
15320 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
15330 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 (N+1)*C strings
15340 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 where the first
15350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 .** C s
15360 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d trings are colum
15370 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 n names as obtai
15380 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 ned from.**
15390 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f [sqlite3_co
153a0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 lumn_name()] and
153b0 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f the rest are co
153c0 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 lumn result valu
153d0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f es.** o
153e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
153f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
15400 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 t()]..**.** {H12
15410 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 379} The values
15420 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 in the pazResult
15430 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 array returned
15440 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f by [sqlite3_get_
15450 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 table()].**
15460 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 shall remai
15470 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c n valid until cl
15480 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eared by [sqlite
15490 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 3_free_table()].
154a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 .**.** {H12382}
154b0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
154c0 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c curs during eval
154d0 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 uation of [sqlit
154e0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a e3_get_table()].
154f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
15500 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 function shall s
15510 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f et *pazResult to
15520 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 NULL, write an
15530 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a error message.**
15540 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d into m
15550 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
15560 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
15570 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 loc()], make.**
15580 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 **pzErr
15590 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 msg point to tha
155a0 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c t error message,
155b0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a and return a.**
155c0 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 approp
155d0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
155e0 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 e]..*/.int sqlit
155f0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 e3_get_table(.
15600 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
15610 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
15620 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
15630 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
15640 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
15650 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
15660 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 char ***pazResu
15670 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 lt, /* Result
15680 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a s of the query *
15690 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 /. int *pnRow,
156a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
156b0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f ber of result ro
156c0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ws written here
156d0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 */. int *pnColu
156e0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 mn, /* Nu
156f0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 mber of result c
15700 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 olumns written h
15710 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ere */. char **
15720 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f pzErrmsg /
15730 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
15740 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 ten here */.);.v
15750 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
15760 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 _table(char **re
15770 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 sult);../*.** CA
15780 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 PI3REF: Formatte
15790 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e d String Printin
157a0 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 g Functions {H17
157b0 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 400} <S70000><S2
157c0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0000>.**.** Thes
157d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
157e0 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 orkalikes of the
157f0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
15800 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
15810 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
15820 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
15830 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
15840 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
15850 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
15860 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
15870 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
15880 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
15890 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
158a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
158b0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
158c0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
158d0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
158e0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
158f0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
15900 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 _free()]. Both
15910 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
15920 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
15930 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
15940 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
15950 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
15960 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
15970 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
15980 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
15990 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e ** In sqlite3_sn
159a0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
159b0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
159c0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
159d0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
159e0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
159f0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
15a00 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
15a10 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
15a20 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
15a30 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
15a40 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
15a50 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
15a60 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 eter. Note that
15a70 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 the order of the
15a80 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 .** first two pa
15a90 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 rameters is reve
15aa0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e rsed from snprin
15ab0 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 tf(). This is a
15ac0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 n.** historical
15ad0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 accident that ca
15ae0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 nnot be fixed wi
15af0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a thout breaking.*
15b00 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
15b10 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 atibility. Note
15b20 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
15b30 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
15b40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
15b50 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
15b60 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
15b70 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
15b80 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
15b90 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
15ba0 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 e buffer. We ad
15bb0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
15bc0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
15bd0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
15be0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
15bf0 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
15c00 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
15c10 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
15c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
15c30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
15c40 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
15c50 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
15c60 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 ibility..**.** A
15c70 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
15c80 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
15c90 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
15ca0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
15cb0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
15cc0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
15cd0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
15ce0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 terminated. The
15cf0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
15d00 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
15d10 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
15d20 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
15d30 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
15d40 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
15d50 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
15d60 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
15d70 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
15d80 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
15d90 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
15da0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ters..**.** Thes
15db0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 e routines all i
15dc0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 mplement some ad
15dd0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 ditional formatt
15de0 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 ing.** options t
15df0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 hat are useful f
15e00 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 or constructing
15e10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
15e20 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 ** All of the us
15e30 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 ual printf() for
15e40 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
15e50 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 apply. In addit
15e60 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 ion, there.** is
15e70 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c are "%q", "%Q",
15e80 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
15e90 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 s..**.** The %q
15ea0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
15eb0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
15ec0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
15ed0 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ll-terminated.**
15ee0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
15ef0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
15f00 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
15f10 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
15f20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
15f30 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
15f40 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
15f50 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 ring literal. B
15f60 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 y doubling each
15f70 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 '\''.** characte
15f80 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 r it escapes tha
15f90 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 t character and
15fa0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 allows it to be
15fb0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a inserted into.**
15fc0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a the string..**.
15fd0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** For example,
15fe0 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e assume the strin
15ff0 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 g variable zText
16000 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 contains text a
16010 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
16020 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
16030 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 e>.** char *zTe
16040 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 xt = "It's a hap
16050 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 py day!";.** </p
16060 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
16070 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 .**.** One can u
16080 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 se this text in
16090 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
160a0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
160b0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
160c0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
160d0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
160e0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
160f0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
16100 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a '%q')", zText);.
16110 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
16120 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
16130 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
16140 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
16150 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
16160 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 te>.**.** Becaus
16170 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 e the %q format
16180 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 string is used,
16190 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 the '\'' charact
161a0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 er in zText.** i
161b0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 s escaped and th
161c0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 e SQL generated
161d0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
161e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
161f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
16200 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
16210 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 LUES('It''s a ha
16220 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f ppy day!').** </
16230 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
16240 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 >.**.** This is
16250 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 correct. Had we
16260 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 used %s instead
16270 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 of %q, the gene
16280 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 rated SQL.** wou
16290 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c ld have looked l
162a0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
162b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
162c0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
162d0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
162e0 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 'It's a happy da
162f0 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c y!');.** </pre><
16300 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
16310 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 ** This second e
16320 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c xample is an SQL
16330 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 syntax error.
16340 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c As a general rul
16350 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 e you should.**
16360 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e always use %q in
16370 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e stead of %s when
16380 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 inserting text
16390 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 into a string li
163a0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 teral..**.** The
163b0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
163c0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
163d0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
163e0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
163f0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
16400 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
16410 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
16420 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
16430 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
16440 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
16450 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
16460 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
16470 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
16480 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
16490 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c le quotes) in pl
164a0 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 ace of the %Q op
164b0 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 tion. So, for e
164c0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
164d0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
164e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
164f0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
16500 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
16510 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
16520 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
16530 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
16540 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
16550 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
16560 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
16570 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
16580 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
16590 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
165a0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
165b0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
165c0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
165d0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
165e0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
165f0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
16600 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
16610 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 The "%z" format
16620 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
16630 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 s exactly like "
16640 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 %s" with the.**
16650 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
16660 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
16670 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
16680 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
16690 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
166a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
166b0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
166c0 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 put string. {END
166d0 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e }.**.** INVARIAN
166e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 TS:.**.** {H1740
166f0 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 3} The [sqlite3
16700 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 _mprintf()] and
16710 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 [sqlite3_vmprint
16720 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a f()] interfaces.
16730 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 ** ret
16740 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 urn either point
16750 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d ers to zero-term
16760 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
16770 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 ings held in.**
16780 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 memory
16790 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
167a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
167b0 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ] or NULL pointe
167c0 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 rs if.**
167d0 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 a call to [sq
167e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
167f0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 fails..**.** {H1
16800 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 7406} The [sqli
16810 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
16820 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 interface writes
16830 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
16840 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ed.**
16850 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 UTF-8 string int
16860 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 o the buffer poi
16870 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 nted to by the s
16880 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a econd parameter.
16890 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f ** pro
168a0 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 vided that the f
168b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
168c0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a s greater than z
168d0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 ero..**.** {H174
168e0 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 07} The [sqlite
168f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 3_snprintf()] in
16900 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
16910 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a write slots of.
16920 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 ** its
16930 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 output buffer (
16940 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
16950 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 eter) outside th
16960 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 e range.**
16970 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 of 0 throug
16980 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 h N-1 (where N i
16990 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
169a0 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 meter).**
169b0 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f regardless o
169c0 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 f the length of
169d0 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 the string.**
169e0 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 requeste
169f0 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 d by the format
16a00 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a specification..*
16a10 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f /.char *sqlite3_
16a20 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
16a30 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a ar*,...);.char *
16a40 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
16a50 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
16a60 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 _list);.char *sq
16a70 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 lite3_snprintf(i
16a80 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
16a90 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a har*, ...);../*.
16aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
16ab0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 ory Allocation S
16ac0 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 ubsystem {H17300
16ad0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a } <S20000>.**.**
16ae0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
16af0 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 uses these thr
16b00 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 ee routines for
16b10 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a all of its own.*
16b20 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 * internal memor
16b30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
16b40 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 ds. "Core" in th
16b50 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 e previous sente
16b60 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 nce.** does not
16b70 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e include operatin
16b80 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 g-system specifi
16b90 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 c VFS implementa
16ba0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 tion. The.** Wi
16bb0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e ndows VFS uses n
16bc0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 ative malloc() a
16bd0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f nd free() for so
16be0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a me operations..*
16bf0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
16c00 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e _malloc() routin
16c10 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
16c20 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a ter to a block.*
16c30 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c * of memory at l
16c40 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
16c50 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 length, where N
16c60 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 is the parameter
16c70 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f ..** If sqlite3_
16c80 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 malloc() is unab
16c90 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 le to obtain suf
16ca0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 ficient free.**
16cb0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 memory, it retur
16cc0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
16cd0 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d r. If the param
16ce0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c eter N to.** sql
16cf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
16d00 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 zero or negativ
16d10 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d e then sqlite3_m
16d20 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a alloc() returns.
16d30 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
16d40 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 r..**.** Calling
16d50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
16d60 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 with a pointer p
16d70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
16d80 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
16d90 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
16da0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
16db0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d eleases that mem
16dc0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 ory so.** that i
16dd0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 t might be reuse
16de0 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f d. The sqlite3_
16df0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 free() routine i
16e00 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 s.** a no-op if
16e10 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
16e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
16e30 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 Passing a NULL p
16e40 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c ointer.** to sql
16e50 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 ite3_free() is h
16e60 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 armless. After
16e70 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d being freed, mem
16e80 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 ory.** should ne
16e90 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f ither be read no
16ea0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e r written. Even
16eb0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 reading previou
16ec0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d sly freed.** mem
16ed0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 ory might result
16ee0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 in a segmentati
16ef0 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 on fault or othe
16f00 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a r severe error..
16f10 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 ** Memory corrup
16f20 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 tion, a segmenta
16f30 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f tion fault, or o
16f40 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
16f50 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c r.** might resul
16f60 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 t if sqlite3_fre
16f70 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 e() is called wi
16f80 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f th a non-NULL po
16f90 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 inter that.** wa
16fa0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 s not obtained f
16fb0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
16fc0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
16fd0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a realloc()..**.**
16fe0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 The sqlite3_rea
16ff0 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 lloc() interface
17000 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 attempts to res
17010 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d ize a.** prior m
17020 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
17030 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 to be at least
17040 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e N bytes, where N
17050 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e is the.** secon
17060 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 d parameter. Th
17070 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
17080 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 ion to be resize
17090 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a d is the first.*
170a0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 * parameter. If
170b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
170c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
170d0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 realloc().** is
170e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
170f0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
17100 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
17110 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
17120 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 te3_malloc(N) wh
17130 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
17140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
17150 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
17160 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 ()..** If the se
17170 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
17180 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
17190 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a c() is zero or.*
171a0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 * negative then
171b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
171c0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 exactly the same
171d0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 as calling.** s
171e0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 qlite3_free(P) w
171f0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 here P is the fi
17200 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
17210 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
17220 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 ()..** sqlite3_r
17230 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 ealloc() returns
17240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
17250 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
17260 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 n.** of at least
17270 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
17280 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 or NULL if suff
17290 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 icient memory is
172a0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
172b0 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a If M is the siz
172c0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 e of the prior a
172d0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 llocation, then
172e0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a min(N,M) bytes.*
172f0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 * of the prior a
17300 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f llocation are co
17310 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 pied into the be
17320 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 ginning of buffe
17330 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 r returned.** by
17340 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
17350 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 () and the prior
17360 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 allocation is f
17370 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 reed..** If sqli
17380 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
17390 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e turns NULL, then
173a0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
173b0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 ation.** is not
173c0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 freed..**.** The
173d0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 memory returned
173e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
173f0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 oc() and sqlite3
17400 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 _realloc().** is
17410 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 always aligned
17420 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 to at least an 8
17430 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 byte boundary.
17440 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 {END}.**.** The
17450 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e default implemen
17460 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 tation of the me
17470 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
17480 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a subsystem uses.*
17490 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 * the malloc(),
174a0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 realloc() and fr
174b0 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 ee() provided by
174c0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
174d0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 library..** {H17
174e0 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 382} However, if
174f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
17500 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
17510 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 SQLITE_MEMORY_SI
17520 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 ZE=<i>NNN</i> C
17530 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
17540 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e ro (where <i>NNN
17550 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e </i>.** is an in
17560 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c teger), then SQL
17570 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61 ite create a sta
17580 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 tic array of at
17590 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c least.** <i>NNN<
175a0 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a /i> bytes in siz
175b0 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 e and uses that
175c0 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 array for all of
175d0 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 its dynamic.**
175e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
175f0 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 n needs. {END}
17600 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 Additional memor
17610 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 y allocator opti
17620 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 ons.** may be ad
17630 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
17640 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e leases..**.** In
17650 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
17660 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 3.5.0 and 3.5.1,
17670 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 it was possible
17680 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 to define.** th
17690 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 e SQLITE_OMIT_ME
176a0 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 MORY_ALLOCATION
176b0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 which would caus
176c0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a e the built-in.*
176d0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
176e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
176f0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 es to be omitted
17700 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 . That capabili
17710 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 ty.** is no long
17720 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e er provided. On
17730 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f ly built-in memo
17740 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 ry allocators ca
17750 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a n be used..**.**
17760 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 The Windows OS
17770 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 interface layer
17780 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 calls.** the sys
17790 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 tem malloc() and
177a0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 free() directly
177b0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 when converting
177c0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 .** filenames be
177d0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 tween the UTF-8
177e0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 encoding used by
177f0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 SQLite.** and w
17800 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 hatever filename
17810 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 encoding is use
17820 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 d by the particu
17830 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 lar Windows.** i
17840 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 nstallation. Me
17850 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
17860 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 errors are detec
17870 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
17880 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 are reported ba
17890 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
178a0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
178b0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
178c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
178d0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 _NOMEM]..**.** I
178e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
178f0 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b {H17303} The [
17900 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
17910 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
17920 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f urns either a po
17930 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 inter to.**
17940 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 a newly ch
17950 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 ecked-out block
17960 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
17970 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a tes of memory.**
17980 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 that
17990 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 is 8-byte aligne
179a0 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 d, or it returns
179b0 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 NULL if it is u
179c0 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 nable.**
179d0 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 to fulfill th
179e0 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a e request..**.**
179f0 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b {H17304} The [
17a00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
17a10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
17a20 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
17a30 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 ter if.**
17a40 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 N is less th
17a50 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
17a60 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 ero..**.** {H173
17a70 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 05} The [sqlite
17a80 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 3_free(P)] inter
17a90 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 face releases me
17aa0 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a mory previously.
17ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 ** ret
17ac0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
17ad0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 te3_malloc()] or
17ae0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
17af0 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 c()],.**
17b00 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 making it ava
17b10 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 ilable for reuse
17b20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d ..**.** {H17306}
17b30 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c A call to [sql
17b40 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d ite3_free(NULL)]
17b50 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
17b60 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 o-op..**.** {H17
17b70 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 310} A call to
17b80 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
17b90 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 (0,N)] is equiva
17ba0 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a lent to a call.*
17bb0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b * to [
17bc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
17bd0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 )]..**.** {H1731
17be0 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 2} A call to [s
17bf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 qlite3_realloc(P
17c00 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 ,0)] is equivale
17c10 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 nt to a call.**
17c20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 to [sq
17c30 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a lite3_free(P)]..
17c40 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 **.** {H17315}
17c50 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
17c60 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 uses [sqlite3_ma
17c70 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
17c80 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 3_realloc()],.**
17c90 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b and [
17ca0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
17cb0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d for all of its m
17cc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
17cd0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
17ce0 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e deallocation n
17cf0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 eeds..**.** {H17
17d00 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 318} The [sqlit
17d10 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d e3_realloc(P,N)]
17d20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
17d30 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e ns either a poin
17d40 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ter.**
17d50 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 to a block of c
17d60 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 hecked-out memor
17d70 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 y of at least N
17d80 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a bytes in size.**
17d90 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 that
17da0 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 is 8-byte aligne
17db0 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 d, or a NULL poi
17dc0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 nter..**.** {H17
17dd0 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 321} When [sqli
17de0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 te3_realloc(P,N)
17df0 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d ] returns a non-
17e00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 NULL pointer, it
17e10 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 first.**
17e20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 copies the f
17e30 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 irst K bytes of
17e40 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 content from P i
17e50 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a nto the newly.**
17e60 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 alloc
17e70 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 ated block, wher
17e80 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 e K is the lesse
17e90 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 r of N and the s
17ea0 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 ize of.**
17eb0 20 20 20 20 74 68 65 20 62 75 66 66 65 72 20 50 the buffer P
17ec0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d ..**.** {H17322}
17ed0 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f When [sqlite3_
17ee0 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 realloc(P,N)] re
17ef0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c turns a non-NULL
17f00 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 pointer, it fir
17f10 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 st.**
17f20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 releases the buf
17f30 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 fer P..**.** {H1
17f40 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 7323} When [sql
17f50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e ite3_realloc(P,N
17f60 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c )] returns NULL,
17f70 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73 the buffer P is
17f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f .** no
17f90 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 t modified or re
17fa0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 leased..**.** AS
17fb0 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a SUMPTIONS:.**.**
17fc0 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 {A17350} The p
17fd0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 ointer arguments
17fe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
17ff0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
18000 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
18010 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 must b
18020 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 e either NULL or
18030 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f else pointers o
18040 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 btained from a p
18050 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 rior.**
18060 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 invocation of
18070 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
18080 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
18090 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
180a0 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ave.**
180b0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
180c0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 leased..**.** {A
180d0 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 17351} The appl
180e0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
180f0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 read or write a
18100 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 ny part of.**
18110 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 a block
18120 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 of memory after
18130 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 it has been rele
18140 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 ased using.**
18150 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
18160 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c _free()] or [sql
18170 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e ite3_realloc()].
18180 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
18190 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 3_malloc(int);.v
181a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
181b0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 lloc(void*, int)
181c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
181d0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a ree(void*);../*.
181e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
181f0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 ory Allocator St
18200 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 atistics {H17370
18210 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a } <S30210>.**.**
18220 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
18230 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
18240 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
18250 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
18260 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
18270 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
18280 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
18290 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
182a0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
182b0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
182c0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
182d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
182e0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
182f0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
18300 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 .** {H17371} The
18310 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
18320 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 _used()] routine
18330 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
18340 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 ber of bytes.**
18350 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f of memo
18360 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
18370 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
18380 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
18390 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 )..**.** {H17373
183a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d } The [sqlite3_m
183b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
183c0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
183d0 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a ns the maximum.*
183e0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
183f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d of [sqlite3_mem
18400 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 ory_used()] sinc
18410 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 e the high-water
18420 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 mark.**
18430 20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 was last reset
18440 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d ..**.** {H17374}
18450 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 The values retu
18460 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
18470 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
18480 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
18490 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
184a0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 highwater()] inc
184b0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 lude any overhea
184c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 d.** ad
184d0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
184e0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
184f0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
18500 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 malloc()],.**
18510 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f but not o
18520 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 verhead added by
18530 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 the any underly
18540 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 ing system libra
18550 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 ry.** r
18560 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 outines that [sq
18570 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
18580 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 may call..**.**
18590 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d {H17375} The mem
185a0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d ory high-water m
185b0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 ark is reset to
185c0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
185d0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 e of.**
185e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
185f0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 _used()] if and
18600 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 only if the para
18610 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 meter to.**
18620 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 [sqlite3_me
18630 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
18640 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 ] is true. The
18650 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a value returned.*
18660 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 * by [s
18670 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
18680 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
18690 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
186a0 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 rk.** p
186b0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 rior to the rese
186c0 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e t..*/.sqlite3_in
186d0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
186e0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 ry_used(void);.s
186f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
18700 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
18710 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 water(int resetF
18720 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 lag);../*.** CAP
18730 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 I3REF: Pseudo-Ra
18740 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 ndom Number Gene
18750 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c rator {H17390} <
18760 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S20000>.**.** SQ
18770 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 Lite contains a
18780 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
18790 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 udo-random numbe
187a0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e r generator (PRN
187b0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 G) used to.** se
187c0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 lect random [ROW
187d0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 ID | ROWIDs] whe
187e0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 n inserting new
187f0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 records into a t
18800 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 able that.** alr
18810 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 eady uses the la
18820 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b rgest possible [
18830 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e ROWID]. The PRN
18840 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 G is also used f
18850 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d or.** the build-
18860 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 in random() and
18870 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c randomblob() SQL
18880 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 functions. Thi
18890 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
188a0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f ws.** applicatio
188b0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ns to access the
188c0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f same PRNG for o
188d0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a ther purposes..*
188e0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 *.** A call to t
188f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
18900 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
18910 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
18920 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 ffer P..**.** Th
18930 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 e first time thi
18940 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 s routine is inv
18950 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 oked (either int
18960 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a ernally or by.**
18970 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
18980 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 ) the PRNG is se
18990 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f eded using rando
189a0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a mness obtained.*
189b0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 * from the xRand
189c0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 omness method of
189d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
189e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
189f0 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 t..** On all sub
18a00 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 sequent invocati
18a10 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d ons, the pseudo-
18a20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 randomness is ge
18a30 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 nerated.** inter
18a40 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 nally and withou
18a50 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 t recourse to th
18a60 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
18a70 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d xRandomness.** m
18a80 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 ethod..**.** INV
18a90 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
18aa0 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c H17392} The [sql
18ab0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
18ac0 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 N,P)] interface
18ad0 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f writes N bytes o
18ae0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 f.** hi
18af0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 gh-quality pseud
18b00 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 o-randomness int
18b10 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 o buffer P..*/.v
18b20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 oid sqlite3_rand
18b30 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f omness(int N, vo
18b40 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id *P);../*.** C
18b50 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 API3REF: Compile
18b60 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 -Time Authorizat
18b70 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 ion Callbacks {H
18b80 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 12500} <S70100>.
18b90 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
18ba0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 ne registers a a
18bb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
18bc0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ck with a partic
18bd0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
18be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 e connection], s
18bf0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 upplied in the f
18c00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
18c10 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
18c20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
18c30 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
18c40 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
18c50 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
18c60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
18c70 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
18c80 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
18c90 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
18ca0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
18cb0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 6()] and [sqlite
18cc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
18cd0 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a ]. At various.*
18ce0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 * points during
18cf0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 the compilation
18d00 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 process, as logi
18d10 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 c is being creat
18d20 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d ed.** to perform
18d30 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 various actions
18d40 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 , the authorizer
18d50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
18d60 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 oked to.** see i
18d70 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 f those actions
18d80 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 are allowed. Th
18d90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
18da0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 lback should.**
18db0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
18dc0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 K] to allow the
18dd0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f action, [SQLITE_
18de0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c IGNORE] to disal
18df0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 low the.** speci
18e00 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 fic action but a
18e10 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 llow the SQL sta
18e20 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e tement to contin
18e30 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ue to be.** comp
18e40 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 iled, or [SQLITE
18e50 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 _DENY] to cause
18e60 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 the entire SQL s
18e70 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a tatement to be.*
18e80 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 * rejected with
18e90 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 an error. If th
18ea0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
18eb0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a lback returns.**
18ec0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 any value other
18ed0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 than [SQLITE_IG
18ee0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f NORE], [SQLITE_O
18ef0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 K], or [SQLITE_D
18f00 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ENY].** then the
18f10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
18f20 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
18f30 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
18f40 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 triggered.** the
18f50 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
18f60 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
18f70 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a ror message..**.
18f80 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ** When the call
18f90 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
18fa0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d LITE_OK], that m
18fb0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 eans the operati
18fc0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 on.** requested
18fd0 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 is ok. When the
18fe0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
18ff0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c s [SQLITE_DENY],
19000 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
19010 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
19020 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
19030 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
19040 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
19050 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
19060 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
19070 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 ge explaining th
19080 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 at.** access is
19090 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 denied. If the
190a0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 authorizer code
190b0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d is [SQLITE_READ]
190c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c .** and the call
190d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
190e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
190f0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
19100 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 ed statement] st
19110 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 atement is const
19120 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 ructed to substi
19130 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 tute.** a NULL v
19140 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 alue in place of
19150 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
19160 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 n that would hav
19170 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 e.** been read i
19180 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 f [SQLITE_OK] ha
19190 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e d been returned.
191a0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 The [SQLITE_IG
191b0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 NORE].** return
191c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 can be used to d
191d0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 eny an untrusted
191e0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 user access to
191f0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f individual.** co
19200 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 lumns of a table
19210 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
19220 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
19230 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
19240 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
19250 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a of the third.**
19260 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
19270 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
19280 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 thorizer() inter
19290 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 face. The second
192a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
192b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
192c0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
192d0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
192e0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
192f0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
19300 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
19310 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
19320 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f . The third thro
19330 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
19340 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ters.** to the c
19350 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f allback are zero
19360 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
19370 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
19380 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 additional.** d
19390 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
193a0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
193b0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
193c0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 An authorizer is
193d0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 used when [sqli
193e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
193f0 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 eparing].** SQL
19400 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 statements from
19410 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 an untrusted sou
19420 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 rce, to ensure t
19430 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 hat the SQL stat
19440 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 ements.** do not
19450 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 try to access d
19460 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 ata they are not
19470 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c allowed to see,
19480 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f or that they do
19490 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 not.** try to e
194a0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 xecute malicious
194b0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 statements that
194c0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 damage the data
194d0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 base. For.** ex
194e0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 ample, an applic
194f0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 ation may allow
19500 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 a user to enter
19510 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c arbitrary.** SQL
19520 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 queries for eva
19530 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 luation by a dat
19540 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 abase. But the
19550 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
19560 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 .** not want the
19570 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 user to be able
19580 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 to make arbitra
19590 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 ry changes to th
195a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 e.** database.
195b0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f An authorizer co
195c0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 uld then be put
195d0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 in place while t
195e0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 he.** user-enter
195f0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 ed SQL is being
19600 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
19610 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 | prepared] tha
19620 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 t.** disallows e
19630 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 verything except
19640 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
19650 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c ents..**.** Appl
19660 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 ications that ne
19670 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 ed to process SQ
19680 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 L from untrusted
19690 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 sources.** migh
196a0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 t also consider
196b0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 lowering resourc
196c0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b e limits using [
196d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
196e0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 .** and limiting
196f0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 database size u
19700 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 sing the [max_pa
19710 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
19720 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f A].** in additio
19730 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 n to using an au
19740 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 thorizer..**.**
19750 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 Only a single au
19760 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 thorizer can be
19770 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 in place on a da
19780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19790 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 n.** at a time.
197a0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
197b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
197c0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 izer overrides t
197d0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 he.** previous c
197e0 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 all. Disable th
197f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 e authorizer by
19800 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c installing a NUL
19810 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 L callback..** T
19820 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 he authorizer is
19830 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
19840 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ault..**.** The
19850 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
19860 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
19870 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
19880 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
19890 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
198a0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
198b0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
198c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f callback..** No
198d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
198e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
198f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
19900 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
19910 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
19920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
19930 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
19940 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
19950 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
19960 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 ** When [sqlite3
19970 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 _prepare_v2()] i
19980 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 s used to prepar
19990 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 e a statement, t
199a0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 he.** statement
199b0 6d 69 67 68 74 20 62 65 20 72 65 70 72 65 70 61 might be reprepa
199c0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 red during [sqli
199d0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 te3_step()] due
199e0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 to a .** schema
199f0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 change. Hence,
19a00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
19a10 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 should ensure th
19a20 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 at the.** correc
19a30 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c t authorizer cal
19a40 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e lback remains in
19a50 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 place during th
19a60 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
19a70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 )]..**.** Note t
19a80 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a hat the authoriz
19a90 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
19aa0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 nvoked only duri
19ab0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ng.** [sqlite3_p
19ac0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
19ad0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 variants. Auth
19ae0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 orization is not
19af0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 .** performed du
19b00 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 ring statement e
19b10 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 valuation in [sq
19b20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
19b30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
19b40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 .**.** {H12501}
19b50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
19b60 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e _authorizer(D,..
19b70 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 .)] interface re
19b80 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 gisters a.**
19b90 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 authorizer
19ba0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 callback with d
19bb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19bc0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 on D..**.** {H12
19bd0 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 502} The authori
19be0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
19bf0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
19c00 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a tatements are.**
19c10 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 being
19c20 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70 parseed and comp
19c30 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 iled..**.** {H12
19c40 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 503} If the auth
19c50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
19c60 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 returns any valu
19c70 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 e other than.**
19c80 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
19c90 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 _IGNORE], [SQLIT
19ca0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 E_OK], or [SQLIT
19cb0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a E_DENY], then.**
19cc0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 70 the ap
19cd0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 plication interf
19ce0 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 ace call that ca
19cf0 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 used.**
19d00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
19d10 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 callback to run
19d20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 shall fail with
19d30 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b an.** [
19d40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 SQLITE_ERROR] er
19d50 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 ror code and an
19d60 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f appropriate erro
19d70 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a r message..**.**
19d80 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74 {H12504} When t
19d90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
19da0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
19db0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 SQLITE_OK], the
19dc0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 operation.**
19dd0 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20 described
19de0 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 is processed nor
19df0 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 mally..**.** {H1
19e00 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 2505} When the a
19e10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
19e20 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
19e30 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
19e40 20 20 20 20 20 20 20 20 20 20 61 70 70 6c 69 63 applic
19e50 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 ation interface
19e60 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 call that caused
19e70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
19e80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
19e90 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c back to run shal
19ea0 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 l fail.**
19eb0 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 with an [SQLI
19ec0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 TE_ERROR] error
19ed0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f code and an erro
19ee0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 r message.**
19ef0 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 explaining
19f00 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20 that access is
19f10 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 denied..**.** {H
19f20 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 12506} If the au
19f30 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 thorizer code (t
19f40 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
19f50 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
19f60 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 er.** c
19f70 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c allback) is [SQL
19f80 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 ITE_READ] and th
19f90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
19fa0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a lback returns.**
19fb0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
19fc0 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 E_IGNORE], then
19fd0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
19fe0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 tement is constr
19ff0 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 ucted to.**
1a000 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 insert a NU
1a010 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 LL value in plac
1a020 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
1a030 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 olumn that would
1a040 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 have.**
1a050 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b been read if [
1a060 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 SQLITE_OK] had b
1a070 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a een returned..**
1a080 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20 .** {H12507} If
1a090 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1a0a0 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 ode (the 2nd par
1a0b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
1a0c0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 thorizer.**
1a0d0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 callback) i
1a0e0 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 s anything other
1a0f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 than [SQLITE_RE
1a100 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 AD], then.**
1a110 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f a return o
1a120 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 f [SQLITE_IGNORE
1a130 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 ] has the same e
1a140 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 ffect as [SQLITE
1a150 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 _DENY]..**.** {H
1a160 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 12510} The first
1a170 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1a180 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1a190 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
1a1a0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 of.** t
1a1b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
1a1c0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
1a1d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1a1e0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a r()] interface..
1a1f0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 **.** {H12511} T
1a200 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1a210 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ter to the callb
1a220 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
1a230 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 r.** [S
1a240 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
1a250 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
1a260 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72 pecifies the par
1a270 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a ticular action.*
1a280 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 * to be
1a290 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a authorized..**.
1a2a0 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20 ** {H12512} The
1a2b0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 third through si
1a2c0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 xth parameters t
1a2d0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 o the callback a
1a2e0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a re.** z
1a2f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
1a300 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 trings that cont
1a310 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ain.**
1a320 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 additional detai
1a330 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
1a340 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
1a350 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ized..**.** {H12
1a360 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 520} Each call t
1a370 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 o [sqlite3_set_a
1a380 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 uthorizer()] ove
1a390 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 rrides.**
1a3a0 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c any previousl
1a3b0 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 y installed auth
1a3c0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 orizer..**.** {H
1a3d0 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 12521} A NULL au
1a3e0 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 thorizer means t
1a3f0 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 hat no authoriza
1a400 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
1a410 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1a420 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 oked..**.** {H12
1a430 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 522} The default
1a440 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e authorizer is N
1a450 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
1a460 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1a470 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a er(. sqlite3*,.
1a480 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 int (*xAuth)(v
1a490 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
1a4a0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1a4b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
1a4c0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 st char*),. voi
1a4d0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a d *pUserData.);.
1a4e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1a4f0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 Authorizer Retu
1a500 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 rn Codes {H12590
1a510 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a } <H12500>.**.**
1a520 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1a530 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1a540 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1a550 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
1a560 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
1a570 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
1a580 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
1a590 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
1a5a0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
1a5b0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
1a5c0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
1a5d0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
1a5e0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
1a5f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1a600 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1a610 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
1a620 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
1a630 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
1a640 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
1a650 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a TE_DENY 1 /*
1a660 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 Abort the SQL s
1a670 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e tatement with an
1a680 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
1a690 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 e SQLITE_IGNORE
1a6a0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 2 /* Don't all
1a6b0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 ow access, but d
1a6c0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e on't generate an
1a6d0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a error */../*.**
1a6e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f CAPI3REF: Autho
1a6f0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 rizer Action Cod
1a700 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 es {H12550} <H12
1a710 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 500>.**.** The [
1a720 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1a730 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
1a740 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
1a750 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1a760 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 n.** that is inv
1a770 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a oked to authoriz
1a780 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 e certain SQL st
1a790 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
1a7a0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
1a7b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1a7c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
1a7d0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
1a7e0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
1a7f0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
1a800 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
1a810 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
1a820 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
1a830 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
1a840 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1a850 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
1a860 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
1a870 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
1a880 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
1a890 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
1a8a0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 is to be.** aut
1a8b0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 horized. The 3r
1a8c0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
1a8d0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 ters to the auth
1a8e0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c orization.** cal
1a8f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
1a900 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
1a910 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
1a920 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 ing on which of
1a930 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 these.** codes i
1a940 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
1a950 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
1a960 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 The 5th paramet
1a970 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 er to the.** aut
1a980 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1a990 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
1a9a0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d the database ("m
1a9b0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a ain", "temp",.**
1a9c0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 etc.) if applic
1a9d0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 able. The 6th p
1a9e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1a9f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1aa00 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
1aa10 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
1aa20 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
1aa30 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
1aa40 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
1aa50 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
1aa60 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
1aa70 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
1aa80 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
1aa90 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
1aaa0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 SQL code..**.**
1aab0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1aac0 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73 * {H12551} The s
1aad0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1aae0 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 to an.**
1aaf0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 [sqlite3_set_a
1ab00 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
1ab10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d orizer callback]
1ab20 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74 shall be an int
1ab30 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 eger.**
1ab40 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 [SQLITE_COPY |
1ab50 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d authorizer code]
1ab60 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 that specifies
1ab70 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 what action.**
1ab80 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 is being
1ab90 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a authorized..**.
1aba0 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20 ** {H12552} The
1abb0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 3rd and 4th para
1abc0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a meters to the.**
1abd0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1abe0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1abf0 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f r | authorizatio
1ac00 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 n callback].**
1ac10 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65 shall be
1ac20 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e parameters or N
1ac30 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ULL depending on
1ac40 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 which.**
1ac50 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 [SQLITE_COPY
1ac60 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 | authorizer cod
1ac70 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68 e] is used as th
1ac80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1ac90 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 er..**.** {H1255
1aca0 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 3} The 5th param
1acb0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 eter to the.**
1acc0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1acd0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1ace0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
1acf0 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 lback] shall be
1ad00 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 the name.**
1ad10 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 of the data
1ad20 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 base (example: "
1ad30 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 main", "temp", e
1ad40 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 tc.) if applicab
1ad50 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 le..**.** {H1255
1ad60 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 4} The 6th param
1ad70 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 eter to the.**
1ad80 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1ad90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1ada0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
1adb0 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 lback] shall be
1adc0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 the name.**
1add0 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 of the inne
1ade0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f r-most trigger o
1adf0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 r view that is r
1ae00 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a esponsible for.*
1ae10 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 * the a
1ae20 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 ccess attempt or
1ae30 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 NULL if this ac
1ae40 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 cess attempt is
1ae50 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a directly from.**
1ae60 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 top-le
1ae70 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f vel SQL code..*/
1ae80 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
1ae90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1aea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 ************* 3r
1aeb0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 d ************ 4
1aec0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a th ***********/.
1aed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1aee0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 REATE_INDEX
1aef0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 1 /* Inde
1af00 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
1af10 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1af20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1af30 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 EATE_TABLE
1af40 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 2 /* Table
1af50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1af60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1af70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1af80 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ATE_TEMP_INDEX
1af90 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 3 /* Index
1afa0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
1afb0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1afc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1afd0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 TE_TEMP_TABLE
1afe0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 4 /* Table N
1aff0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1b000 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1b010 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1b020 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 E_TEMP_TRIGGER
1b030 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 5 /* Trigger
1b040 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
1b050 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1b060 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1b070 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
1b080 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 6 /* View Name
1b090 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
1b0a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1b0b0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1b0c0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 TRIGGER 7
1b0d0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
1b0e0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
1b0f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b100 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
1b110 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 IEW 8
1b120 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
1b130 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b140 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b150 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 SQLITE_DELETE
1b160 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 9
1b170 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1b180 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1b190 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b1a0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 QLITE_DROP_INDEX
1b1b0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 10
1b1c0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
1b1d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1b1e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b1f0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 LITE_DROP_TABLE
1b200 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 11 /
1b210 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1b220 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b230 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b240 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e ITE_DROP_TEMP_IN
1b250 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a DEX 12 /*
1b260 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
1b270 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1b280 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b290 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 TE_DROP_TEMP_TAB
1b2a0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 LE 13 /*
1b2b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1b2c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1b2d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b2e0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 E_DROP_TEMP_TRIG
1b2f0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 GER 14 /* T
1b300 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
1b310 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1b320 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b330 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 _DROP_TEMP_VIEW
1b340 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 15 /* Vi
1b350 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
1b360 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1b370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b380 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 DROP_TRIGGER
1b390 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 16 /* Tri
1b3a0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
1b3b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1b3c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1b3d0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 ROP_VIEW
1b3e0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 17 /* View
1b3f0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
1b400 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1b410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
1b420 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SERT
1b430 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 18 /* Table
1b440 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1b450 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1b460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 efine SQLITE_PRA
1b470 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 GMA
1b480 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 19 /* Pragma
1b490 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 Name 1st ar
1b4a0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 g or NULL */.#de
1b4b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
1b4c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b4d0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 20 /* Table N
1b4e0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
1b4f0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
1b500 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 ine SQLITE_SELEC
1b510 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
1b520 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 21 /* NULL
1b530 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
1b540 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1b550 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 ne SQLITE_TRANSA
1b560 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 CTION 2
1b570 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 2 /* NULL
1b580 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
1b590 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1b5a0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 e SQLITE_UPDATE
1b5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 23
1b5c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1b5d0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
1b5e0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
1b5f0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 SQLITE_ATTACH
1b600 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 24
1b610 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 /* Filename
1b620 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b630 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b640 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 SQLITE_DETACH
1b650 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 25
1b660 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
1b670 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 e NULL
1b680 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b690 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c QLITE_ALTER_TABL
1b6a0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 E 26
1b6b0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 /* Database Name
1b6c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1b6d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b6e0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 LITE_REINDEX
1b6f0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 27 /
1b700 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
1b710 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b720 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b730 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 ITE_ANALYZE
1b740 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 28 /*
1b750 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1b760 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1b770 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b780 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 TE_CREATE_VTABLE
1b790 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 29 /*
1b7a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1b7b0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
1b7c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b7d0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 E_DROP_VTABLE
1b7e0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 30 /* T
1b7f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d able Name M
1b800 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a odule Name *
1b810 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b820 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 _FUNCTION
1b830 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 31 /* NU
1b840 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 LL Fu
1b850 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f nction Name */
1b860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b870 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 COPY
1b880 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 0 /* No
1b890 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a longer used */..
1b8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b8b0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
1b8c0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 iling Functions
1b8d0 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30 {H12280} <S60400
1b8e0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
1b8f0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f L.**.** These ro
1b900 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 utines register
1b910 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1b920 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 ns that can be u
1b930 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 sed for.** traci
1b940 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 ng and profiling
1b950 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f the execution o
1b960 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 f SQL statements
1b970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
1b980 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
1b990 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
1b9a0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 te3_trace() is i
1b9b0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 nvoked at.** var
1b9c0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 ious times when
1b9d0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
1b9e0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 is being run by
1b9f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1ba00 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 ]..** The callba
1ba10 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 ck returns a UTF
1ba20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
1ba30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1ba40 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 t text.** as the
1ba50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
1ba60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
1ba70 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 g. Additional c
1ba80 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a allbacks occur.*
1ba90 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 * as each trigge
1baa0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 red subprogram i
1bab0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 s entered. The
1bac0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 callbacks for tr
1bad0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 iggers.** contai
1bae0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f n a UTF-8 SQL co
1baf0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 mment that ident
1bb00 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 ifies the trigge
1bb10 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c r..**.** The cal
1bb20 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
1bb30 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c egistered by sql
1bb40 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 ite3_profile() i
1bb50 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 s invoked.** as
1bb60 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 each SQL stateme
1bb70 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 nt finishes. Th
1bb80 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
1bb90 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 ck contains.** t
1bba0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
1bbb0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 ement text and a
1bbc0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 n estimate of wa
1bbd0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a ll-clock time.**
1bbe0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 of how long tha
1bbf0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b t statement took
1bc00 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 to run..**.** I
1bc10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
1bc20 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63 61 {H12281} The ca
1bc30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1bc40 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 registered by [s
1bc50 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 qlite3_trace()]
1bc60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 .** sha
1bc70 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a ll be invoked.**
1bc80 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 whenev
1bc90 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d er an SQL statem
1bca0 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 ent first begins
1bcb0 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a to execute and.
1bcc0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e ** when
1bcd0 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73 ever a trigger s
1bce0 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 ubprogram first
1bcf0 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a begins to run..*
1bd00 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 *.** {H12282} Ea
1bd10 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
1bd20 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68 61 te3_trace()] sha
1bd30 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 ll override the
1bd40 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 previously.**
1bd50 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 registere
1bd60 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b d trace callback
1bd70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d ..**.** {H12283}
1bd80 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 A NULL trace ca
1bd90 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64 69 73 llback shall dis
1bda0 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a able tracing..**
1bdb0 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65 .** {H12284} The
1bdc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
1bdd0 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c to the trace cal
1bde0 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65 20 61 lback shall be a
1bdf0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 copy of.**
1be00 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 the pointer
1be10 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33 which was the 3
1be20 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b rd argument to [
1be30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d sqlite3_trace()]
1be40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d ..**.** {H12285}
1be50 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
1be60 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 ment to the trac
1be70 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a e callback is a.
1be80 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f ** zero
1be90 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
1bea0 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 8 string contain
1beb0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c ing the original
1bec0 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 text.**
1bed0 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 of the SQL sta
1bee0 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 tement as it was
1bef0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 passed into [sq
1bf00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1bf10 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
1bf20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e or the equivalen
1bf30 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d t, or an SQL com
1bf40 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 ment indicating
1bf50 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a the beginning.**
1bf60 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 of a t
1bf70 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 rigger subprogra
1bf80 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 m..**.** {H12287
1bf90 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 } The callback f
1bfa0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
1bfb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ed by [sqlite3_p
1bfc0 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 rofile()] is inv
1bfd0 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 oked.**
1bfe0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 as each SQL sta
1bff0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e tement finishes.
1c000 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 .**.** {H12288}
1c010 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
1c020 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 ter to the profi
1c030 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 le callback is a
1c040 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 copy of.**
1c050 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72 the 3rd par
1c060 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
1c070 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a e3_profile()]..*
1c080 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 *.** {H12289} Th
1c090 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1c0a0 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c er to the profil
1c0b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a e callback is a.
1c0c0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f ** zero
1c0d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
1c0e0 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 8 string that co
1c0f0 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c ntains the compl
1c100 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 ete text of.**
1c110 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 the SQL
1c120 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 statement as it
1c130 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 was processed by
1c140 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1c150 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 e_v2()].**
1c160 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 or the equiv
1c170 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 alent..**.** {H1
1c180 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 2290} The third
1c190 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1c1a0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 profile callbac
1c1b0 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 k is an estimate
1c1c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 .** of
1c1d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 the number of na
1c1e0 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c noseconds of wal
1c1f0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 l-clock time req
1c200 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 uired to.**
1c210 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c run the SQL
1c220 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 statement from
1c230 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e start to finish.
1c240 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 .*/.SQLITE_EXPER
1c250 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 IMENTAL void *sq
1c260 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 lite3_trace(sqli
1c270 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 te3*, void(*xTra
1c280 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 ce)(void*,const
1c290 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a char*), void*);.
1c2a0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
1c2b0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 TAL void *sqlite
1c2c0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 3_profile(sqlite
1c2d0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 3*,. void(*xPr
1c2e0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e ofile)(void*,con
1c2f0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 st char*,sqlite3
1c300 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 _uint64), void*)
1c310 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1c320 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 F: Query Progres
1c330 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 s Callbacks {H12
1c340 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 910} <S60400>.**
1c350 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
1c360 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 configures a ca
1c370 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1c380 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 - the.** progres
1c390 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 s callback - tha
1c3a0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 t is invoked per
1c3b0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 iodically during
1c3c0 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 long.** running
1c3d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
1c3e0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c e3_exec()], [sql
1c3f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 ite3_step()] and
1c400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
1c410 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 _table()]. An e
1c420 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 xample use for t
1c430 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 his.** interface
1c440 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 is to keep a GU
1c450 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 I updated during
1c460 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a a large query..
1c470 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f **.** If the pro
1c480 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 gress callback r
1c490 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
1c4a0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 the operation i
1c4b0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 s.** interrupted
1c4c0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 . This feature
1c4d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 can be used to i
1c4e0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 mplement a.** "C
1c4f0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e ancel" button on
1c500 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 a GUI progress
1c510 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a dialog box..**.*
1c520 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 * The progress h
1c530 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
1c540 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
1c550 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
1c560 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1c570 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
1c580 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 oked the progres
1c590 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f s handler..** No
1c5a0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
1c5b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
1c5c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
1c5d0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
1c5e0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
1c5f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
1c600 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
1c610 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
1c620 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
1c630 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1c640 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 *.** {H12911} Th
1c650 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
1c660 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
1c670 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 y sqlite3_progre
1c680 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 ss_handler().**
1c690 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f is invo
1c6a0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 ked periodically
1c6b0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e during long run
1c6c0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ning calls to.**
1c6d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1c6e0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a e3_step()]..**.*
1c6f0 2a 20 7b 48 31 32 39 31 32 7d 20 54 68 65 20 70 * {H12912} The p
1c700 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
1c710 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 is invoked once
1c720 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 for every N vir
1c730 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 tual.**
1c740 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 machine opcodes
1c750 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
1c760 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1c770 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
1c780 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f the [sqlite3_pro
1c790 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d gress_handler()]
1c7a0 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73 call that regis
1c7b0 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 tered.**
1c7c0 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 the callback.
1c7d0 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 If N is less th
1c7e0 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 an 1, sqlite3_pr
1c7f0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 ogress_handler()
1c800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63 74 .** act
1c810 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 s as if a NULL p
1c820 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
1c830 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66 69 had been specifi
1c840 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 ed..**.** {H1291
1c850 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 3} The progress
1c860 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 callback itself
1c870 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 is identified by
1c880 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 the third.**
1c890 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 argument
1c8a0 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 to sqlite3_progr
1c8b0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a ess_handler()..*
1c8c0 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 *.** {H12914} Th
1c8d0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
1c8e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f t to sqlite3_pro
1c8f0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 gress_handler()
1c900 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 is a.**
1c910 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61 void pointer pa
1c920 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67 ssed to the prog
1c930 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a ress callback.**
1c940 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 functi
1c950 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 on each time it
1c960 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
1c970 2a 20 7b 48 31 32 39 31 35 7d 20 49 66 20 61 20 * {H12915} If a
1c980 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
1c990 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73 _step()] results
1c9a0 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e in fewer than N
1c9b0 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 opcodes.**
1c9c0 20 20 20 20 20 62 65 69 6e 67 20 65 78 65 63 75 being execu
1c9d0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72 ted, then the pr
1c9e0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
1c9f0 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 is never invoked
1ca00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d ..**.** {H12916}
1ca10 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b Every call to [
1ca20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
1ca30 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 _handler()].**
1ca40 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 overwrit
1ca50 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c es any previousl
1ca60 79 20 72 65 67 69 73 74 65 72 65 64 20 70 72 6f y registered pro
1ca70 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
1ca80 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 *.** {H12917} If
1ca90 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
1caa0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 ndler callback i
1cab0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 s NULL then no p
1cac0 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 rogress.**
1cad0 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 handler is i
1cae0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 nvoked..**.** {H
1caf0 31 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 12918} If the pr
1cb00 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
1cb10 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 returns a result
1cb20 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 other than 0, t
1cb30 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
1cb40 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
1cb50 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e a if [sqlite3_in
1cb60 74 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 terrupt()] had b
1cb70 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 een called..**
1cb80 20 20 20 20 20 20 20 20 3c 53 33 30 35 30 30 3e <S30500>
1cb90 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
1cba0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
1cbb0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c r(sqlite3*, int,
1cbc0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
1cbd0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
1cbe0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 API3REF: Opening
1cbf0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 A New Database
1cc00 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 Connection {H127
1cc10 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 00} <S40200>.**.
1cc20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1cc30 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 s open an SQLite
1cc40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
1cc50 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 hose name is giv
1cc60 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c en by the.** fil
1cc70 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 ename argument.
1cc80 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 The filename arg
1cc90 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 ument is interpr
1cca0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f eted as UTF-8 fo
1ccb0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
1ccc0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
1ccd0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 open_v2() and as
1cce0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
1ccf0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 ative byte.** or
1cd00 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f der for sqlite3_
1cd10 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 open16(). A [dat
1cd20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1cd30 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 ] handle is usua
1cd40 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lly.** returned
1cd50 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 in *ppDb, even i
1cd60 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
1cd70 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 s. The only exc
1cd80 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a eption is that.*
1cd90 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 * if SQLite is u
1cda0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
1cdb0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 e memory to hold
1cdc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
1cdd0 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c bject,.** a NULL
1cde0 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e will be written
1cdf0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 into *ppDb inst
1ce00 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 ead of a pointer
1ce10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1ce20 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 ].** object. If
1ce30 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
1ce40 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 opened (and/or c
1ce50 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 reated) successf
1ce60 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 ully, then.** [S
1ce70 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 QLITE_OK] is ret
1ce80 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
1ce90 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
1cea0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 ] is returned.
1ceb0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
1cec0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 errmsg()] or [sq
1ced0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
1cee0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 ] routines can b
1cef0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
1cf00 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c .** an English l
1cf10 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 anguage descript
1cf20 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 ion of the error
1cf30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ..**.** The defa
1cf40 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 ult encoding for
1cf50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 the database wi
1cf60 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a ll be UTF-8 if.*
1cf70 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
1cf80 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
1cf90 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 _v2() is called
1cfa0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e and.** UTF-16 in
1cfb0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
1cfc0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 order if sqlite
1cfd0 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 3_open16() is us
1cfe0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 ed..**.** Whethe
1cff0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f r or not an erro
1d000 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 r occurs when it
1d010 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f is opened, reso
1d020 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 urces.** associa
1d030 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 ted with the [da
1d040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1d050 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 n] handle should
1d060 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a be released by.
1d070 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f ** passing it to
1d080 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
1d090 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f )] when it is no
1d0a0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 longer required
1d0b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1d0c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e te3_open_v2() in
1d0d0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 terface works li
1d0e0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ke sqlite3_open(
1d0f0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ).** except that
1d100 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 it accepts two
1d110 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d additional param
1d120 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 eters for additi
1d130 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 onal control.**
1d140 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 over the new dat
1d150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1d160 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 . The flags par
1d170 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20 ameter can take
1d180 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f one of.** the fo
1d190 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 llowing three va
1d1a0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 lues, optionally
1d1b0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 combined with t
1d1c0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
1d1d0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 PEN_NOMUTEX] or
1d1e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
1d1f0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a LMUTEX] flags:.*
1d200 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
1d210 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
1d220 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 ADONLY]</dt>.**
1d230 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
1d240 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 is opened in re
1d250 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 ad-only mode. I
1d260 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 f the database d
1d270 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 oes not.** alrea
1d280 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 dy exist, an err
1d290 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
1d2a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b /dd>.**.** <dt>[
1d2b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1d2c0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c WRITE]</dt>.** <
1d2d0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
1d2e0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
1d2f0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
1d300 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f g if possible, o
1d310 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c r reading.** onl
1d320 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 y if the file is
1d330 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 write protected
1d340 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e by the operatin
1d350 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 g system. In ei
1d360 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 ther.** case the
1d370 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 database must a
1d380 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 lready exist, ot
1d390 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 herwise an error
1d3a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
1d3b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 d>.**.** <dt>[SQ
1d3c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1d3d0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
1d3e0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
1d3f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
1d400 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
1d410 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
1d420 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
1d430 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 reates it if.**
1d440 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 it does not alre
1d450 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 ady exist. This
1d460 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 is the behavior
1d470 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
1d480 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 sed for.** sqlit
1d490 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
1d4a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c lite3_open16().<
1d4b0 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a /dd>.** </dl>.**
1d4c0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
1d4d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1d4e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1d4f0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
1d500 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
1d510 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f shown above or o
1d520 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e ne of the combin
1d530 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
1d540 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 ve combined.** w
1d550 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
1d560 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 OPEN_NOMUTEX] or
1d570 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
1d580 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a LLMUTEX] flags,.
1d590 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ** then the beha
1d5a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
1d5b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 d..**.** If the
1d5c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
1d5d0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
1d5e0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 t, then the data
1d5f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1d600 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 ** opens in the
1d610 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 multi-thread [th
1d620 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 reading mode] as
1d630 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e long as the sin
1d640 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f gle-thread.** mo
1d650 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 de has not been
1d660 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 set at compile-t
1d670 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
1d680 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 e. If the.** [S
1d690 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
1d6a0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
1d6b0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 t then the datab
1d6c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
1d6d0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 pens.** in the s
1d6e0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
1d6f0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 ding mode] unles
1d700 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s single-thread
1d710 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
1d720 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f y selected at co
1d730 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
1d740 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 art-time..**.**
1d750 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
1d760 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 is ":memory:", t
1d770 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
1d780 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f emporary in-memo
1d790 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 ry database.** i
1d7a0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 s created for th
1d7b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 e connection. T
1d7c0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 his in-memory da
1d7d0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 tabase will vani
1d7e0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 sh when.** the d
1d7f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1d800 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 on is closed. F
1d810 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
1d820 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
1d830 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 * make use of ad
1d840 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c ditional special
1d850 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 filenames that
1d860 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 begin with the "
1d870 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a :" character..**
1d880 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 It is recommend
1d890 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 ed that when a d
1d8a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
1d8b0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 actually does b
1d8c0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 egin with.** a "
1d8d0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 :" character you
1d8e0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 should prefix t
1d8f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 he filename with
1d900 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 a pathname such
1d910 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 as.** "./" to a
1d920 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a void ambiguity..
1d930 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c **.** If the fil
1d940 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 ename is an empt
1d950 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 y string, then a
1d960 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 private, tempor
1d970 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 ary.** on-disk d
1d980 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
1d990 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 created. This p
1d9a0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 rivate database
1d9b0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d will be.** autom
1d9c0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 atically deleted
1d9d0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
1d9e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1d9f0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
1da00 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 *.** The fourth
1da10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1da20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
1da30 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
1da40 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
1da50 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
1da60 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 efines the opera
1da70 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
1da80 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 rface that.** th
1da90 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
1daa0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 onnection should
1dab0 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f use. If the fo
1dac0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
1dad0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
1dae0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 ter then the def
1daf0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
1db00 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 s] object is use
1db10 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 d..**.** <b>Note
1db20 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 to Windows user
1db30 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f s:</b> The enco
1db40 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 ding used for th
1db50 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
1db60 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ent.** of sqlite
1db70 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
1db80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d ite3_open_v2() m
1db90 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f ust be UTF-8, no
1dba0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f t whatever.** co
1dbb0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e depage is curren
1dbc0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 tly defined. Fi
1dbd0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 lenames containi
1dbe0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c ng international
1dbf0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d .** characters m
1dc00 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
1dc10 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 to UTF-8 prior
1dc20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 to passing them
1dc30 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f into.** sqlite3_
1dc40 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
1dc50 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
1dc60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1dc70 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54 68 *.** {H12701} Th
1dc80 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 e [sqlite3_open(
1dc90 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
1dca0 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 n16()], and.**
1dcb0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1dcc0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
1dcd0 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61 20 rfaces create a
1dce0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
1dcf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1dd00 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 tion] associated
1dd10 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 with.**
1dd20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 the database f
1dd30 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 ile given in the
1dd40 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ir first paramet
1dd50 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 er..**.** {H1270
1dd60 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 2} The filename
1dd70 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 argument is inte
1dd80 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 rpreted as UTF-8
1dd90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 .** for
1dda0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
1ddb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f ] and [sqlite3_o
1ddc0 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 pen_v2()] and as
1ddd0 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 UTF-16.**
1dde0 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 in the nativ
1ddf0 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 e byte order for
1de00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
1de10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 ()]..**.** {H127
1de20 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 03} A successful
1de30 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
1de40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
1de50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
1de60 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
1de70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
1de80 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 n_v2()] writes a
1de90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 pointer to a ne
1dea0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 w.** [d
1deb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1dec0 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a on] into *ppDb..
1ded0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54 **.** {H12704} T
1dee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
1def0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1df00 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
1df10 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1df20 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 3_open_v2()] int
1df30 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b erfaces return [
1df40 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 SQLITE_OK] upon
1df50 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 success,.**
1df60 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f or an appro
1df70 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
1df80 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a de] on failure..
1df90 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54 **.** {H12706} T
1dfa0 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 he default text
1dfb0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e encoding for a n
1dfc0 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61 ew database crea
1dfd0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 ted using.**
1dfe0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f [sqlite3_o
1dff0 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 pen()] or [sqlit
1e000 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 e3_open_v2()] wi
1e010 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a ll be UTF-8..**.
1e020 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65 20 ** {H12707} The
1e030 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 default text enc
1e040 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 oding for a new
1e050 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 database created
1e060 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 using.**
1e070 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e [sqlite3_open
1e080 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 16()] will be UT
1e090 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 F-16..**.** {H12
1e0a0 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 709} The [sqlite
1e0b0 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 3_open(F,D)] int
1e0c0 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 erface is equiva
1e0d0 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 lent to.**
1e0e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 [sqlite3_ope
1e0f0 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 n_v2(F,D,G,0)] w
1e100 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d here the G param
1e110 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 eter is.**
1e120 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e [SQLITE_OPEN
1e130 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c _READWRITE]|[SQL
1e140 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
1e150 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d ..**.** {H12711}
1e160 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 If the G parame
1e170 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
1e180 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 open_v2(F,D,G,V)
1e190 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a ] contains the.*
1e1a0 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 * bit v
1e1b0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 alue [SQLITE_OPE
1e1c0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e N_READONLY] then
1e1d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
1e1e0 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 opened.**
1e1f0 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 for reading
1e200 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 only..**.** {H12
1e210 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 712} If the G pa
1e220 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
1e230 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c te3_open_v2(F,D,
1e240 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 G,V)] contains t
1e250 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 he.** b
1e260 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 it value [SQLITE
1e270 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
1e280 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
1e290 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 se is opened.**
1e2a0 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 reading
1e2b0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 and writing if
1e2c0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 possible, or for
1e2d0 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 reading only if
1e2e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1e2f0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 file is write p
1e300 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 rotected by the
1e310 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
1e320 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d ..**.** {H12713}
1e330 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 If the G parame
1e340 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
1e350 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 open_v2(F,D,G,V)
1e360 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 ] omits the.**
1e370 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 bit valu
1e380 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 e [SQLITE_OPEN_C
1e390 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 REATE] and the d
1e3a0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
1e3b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 .** pre
1e3c0 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 viously exist, a
1e3d0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
1e3e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 ned..**.** {H127
1e3f0 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 14} If the G par
1e400 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
1e410 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 e3_open_v2(F,D,G
1e420 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 ,V)] contains th
1e430 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 e.** bi
1e440 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f t value [SQLITE_
1e450 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 OPEN_CREATE] and
1e460 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f the database do
1e470 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 es not.**
1e480 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 previously ex
1e490 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 ist, then an att
1e4a0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 empt is made to
1e4b0 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 create and.**
1e4c0 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a initializ
1e4d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a e the database..
1e4e0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49 **.** {H12717} I
1e4f0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 f the filename a
1e500 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
1e510 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
1e520 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
1e530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
1e540 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1e550 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a ()] is ":memory:
1e560 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 ", then an priva
1e570 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 te,.**
1e580 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 ephemeral, in-me
1e590 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73 mory database is
1e5a0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 created for the
1e5b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 connection..**
1e5c0 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 <todo>I
1e5d0 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 s SQLITE_OPEN_CR
1e5e0 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e EATE|SQLITE_OPEN
1e5f0 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69 _READWRITE requi
1e600 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 red.**
1e610 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f in sqlite3_open_
1e620 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a v2()?</todo>.**.
1e630 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20 74 ** {H12719} If t
1e640 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e he filename is N
1e650 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 ULL or an empty
1e660 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 string, then a p
1e670 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 rivate,.**
1e680 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e ephemeral on
1e690 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 -disk database w
1e6a0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a ill be created..
1e6b0 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 ** <tod
1e6c0 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e o>Is SQLITE_OPEN
1e6d0 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f _CREATE|SQLITE_O
1e6e0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 PEN_READWRITE re
1e6f0 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 quired.**
1e700 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 in sqlite3_op
1e710 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a en_v2()?</todo>.
1e720 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54 **.** {H12721} T
1e730 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1e740 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 nection] created
1e750 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 by [sqlite3_ope
1e760 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a n_v2(F,D,G,V)].*
1e770 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 * will
1e780 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 use the [sqlite3
1e790 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 _vfs] object ide
1e7a0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 56 ntified by the V
1e7b0 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 parameter,.**
1e7c0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 64 or the d
1e7d0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
1e7e0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 vfs] object if V
1e7f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1e800 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 er..**.** {H1272
1e810 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65 3} Two [database
1e820 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 connections] wi
1e830 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f ll share a commo
1e840 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68 20 n cache if both
1e850 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 were.**
1e860 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68 65 opened with the
1e870 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20 same VFS while
1e880 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
1e890 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20 de] was enabled
1e8a0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
1e8b0 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 if both filename
1e8c0 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 s compare equal
1e8d0 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 using memcmp() a
1e8e0 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e fter having been
1e8f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f .** pro
1e900 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b 73 cessed by the [s
1e910 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75 qlite3_vfs | xFu
1e920 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 llPathname] meth
1e930 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a od of the VFS..*
1e940 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 /.int sqlite3_op
1e950 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 en(. const char
1e960 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
1e970 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
1e980 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
1e990 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
1e9a0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
1e9b0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
1e9c0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
1e9d0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e e3_open16(. con
1e9e0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d st void *filenam
1e9f0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 e, /* Database
1ea00 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 filename (UTF-1
1ea10 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 6) */. sqlite3
1ea20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
1ea30 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
1ea40 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
1ea50 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nt sqlite3_open_
1ea60 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 v2(. const char
1ea70 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
1ea80 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
1ea90 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
1eaa0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 sqlite3 **ppDb,
1eab0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
1eac0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
1ead0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c */. int flags,
1eae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
1eaf0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 Flags */. cons
1eb00 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 t char *zVfs
1eb10 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 /* Name of V
1eb20 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 FS module to use
1eb30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
1eb40 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f PI3REF: Error Co
1eb50 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 des And Messages
1eb60 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30 {H12800} <S6020
1eb70 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
1eb80 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
1eb90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
1eba0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 the numeric [re
1ebb0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a sult code] or.**
1ebc0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
1ebd0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 t code] for the
1ebe0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c most recent fail
1ebf0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 ed sqlite3_* API
1ec00 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 call.** associa
1ec10 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 ted with a [data
1ec20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1ec30 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 . If a prior API
1ec40 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 call failed.**
1ec50 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 but the most rec
1ec60 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 ent API call suc
1ec70 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 ceeded, the retu
1ec80 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a rn value from.**
1ec90 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
1eca0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
1ecb0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 The sqlite3_ex
1ecc0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
1ecd0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
1ece0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
1ecf0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
1ed00 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
1ed10 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
1ed20 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
1ed30 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
1ed40 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
1ed50 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 sabled..**.** Th
1ed60 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 e sqlite3_errmsg
1ed70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 () and sqlite3_e
1ed80 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e rrmsg16() return
1ed90 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
1eda0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 e.** text that d
1edb0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
1edc0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 or, as either UT
1edd0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 F-8 or UTF-16 re
1ede0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d spectively..** M
1edf0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
1ee00 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
1ee10 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 string is manage
1ee20 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a d internally..**
1ee30 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
1ee40 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
1ee50 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 o worry about fr
1ee60 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 eeing the result
1ee70 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
1ee80 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d e error string m
1ee90 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 ight be overwrit
1eea0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 ten or deallocat
1eeb0 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 ed by.** subsequ
1eec0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 ent calls to oth
1eed0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
1eee0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ace functions..*
1eef0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 *.** When the se
1ef00 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
1ef10 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 ing mode] is in
1ef20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 use, it might be
1ef30 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 the.** case tha
1ef40 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 t a second error
1ef50 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 occurs on a sep
1ef60 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 arate thread in
1ef70 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 between.** the t
1ef80 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 ime of the first
1ef90 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 error and the c
1efa0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 all to these int
1efb0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e erfaces..** When
1efc0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 that happens, t
1efd0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 he second error
1efe0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 will be reported
1eff0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 since these.**
1f000 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 interfaces alway
1f010 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 s report the mos
1f020 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e t recent result.
1f030 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 To avoid.** th
1f040 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 is, each thread
1f050 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 can obtain exclu
1f060 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 sive use of the
1f070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1f080 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e tion] D.** by in
1f090 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f voking [sqlite3_
1f0a0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 mutex_enter]([sq
1f0b0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 lite3_db_mutex](
1f0c0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e D)) before begin
1f0d0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 ning.** to use D
1f0e0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 and invoking [s
1f0f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
1f100 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f ve]([sqlite3_db_
1f110 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 mutex](D)) after
1f120 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f .** all calls to
1f130 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 the interfaces
1f140 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 listed here are
1f150 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a completed..**.**
1f160 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 If an interface
1f170 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 fails with SQLI
1f180 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 TE_MISUSE, that
1f190 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 means the interf
1f1a0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b ace.** was invok
1f1b0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 ed incorrectly b
1f1c0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
1f1d0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 n. In that case
1f1e0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 , the.** error c
1f1f0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 ode and message
1f200 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 may or may not b
1f210 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 e set..**.** INV
1f220 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
1f230 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c H12801} The [sql
1f240 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d ite3_errcode(D)]
1f250 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
1f260 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a ns the numeric.*
1f270 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65 73 75 * [resu
1f280 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 lt code] or [ext
1f290 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
1f2a0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 e] for the most
1f2b0 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 recently.**
1f2c0 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 failed inte
1f2d0 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 rface call assoc
1f2e0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b iated with the [
1f2f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1f300 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ion] D..**.** {H
1f310 31 32 38 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 12802} The [sqli
1f320 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
1f330 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 code(D)] interfa
1f340 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
1f350 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 umeric.**
1f360 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 [extended res
1f370 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ult code] for th
1f380 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a e most recently.
1f390 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c ** fail
1f3a0 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c ed interface cal
1f3b0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 l associated wit
1f3c0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
1f3d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a connection] D..*
1f3e0 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 *.** {H12803} Th
1f3f0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 e [sqlite3_errms
1f400 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 g(D)] and [sqlit
1f410 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a e3_errmsg16(D)].
1f420 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
1f430 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e rfaces return En
1f440 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
1f450 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 ext that describ
1f460 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 es.** t
1f470 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 he error in the
1f480 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 mostly recently
1f490 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 failed interface
1f4a0 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 call,.**
1f4b0 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 encoded as ei
1f4c0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
1f4d0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c F-16 respectivel
1f4e0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 y..**.** {H12807
1f4f0 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 } The strings re
1f500 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1f510 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 e3_errmsg()] and
1f520 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1f530 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 16()].**
1f540 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 are valid unti
1f550 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 l the next SQLit
1f560 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c e interface call
1f570 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d ..**.** {H12808}
1f580 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f Calls to API ro
1f590 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e utines that do n
1f5a0 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 ot return an err
1f5b0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 or code.**
1f5c0 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 (example: [s
1f5d0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
1f5e0 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 t()]) do not.**
1f5f0 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 change
1f600 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f the error code o
1f610 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e r message return
1f620 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
1f630 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f [sqlite3_errco
1f640 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f de()], [sqlite3_
1f650 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
1f660 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
1f670 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1f680 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 ()], or [sqlite3
1f690 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a _errmsg16()]..**
1f6a0 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 .** {H12809} Int
1f6b0 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 erfaces that are
1f6c0 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 not associated
1f6d0 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a with a specific.
1f6e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 ** [dat
1f6f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1f700 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 ] (examples:.**
1f710 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1f720 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 3_mprintf()] or
1f730 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f [sqlite3_enable_
1f740 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a shared_cache()].
1f750 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e ** do n
1f760 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
1f770 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
1f780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1f790 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
1f7a0 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e , [sqlite3_exten
1f7b0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a ded_errcode()],.
1f7c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1f7d0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 ite3_errmsg()],
1f7e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
1f7f0 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 sg16()]..*/.int
1f800 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
1f810 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e sqlite3 *db);.in
1f820 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
1f830 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 ed_errcode(sqlit
1f840 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 e3 *db);.const c
1f850 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 har *sqlite3_err
1f860 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 msg(sqlite3*);.c
1f870 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
1f880 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 e3_errmsg16(sqli
1f890 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1f8a0 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 PI3REF: SQL Stat
1f8b0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 ement Object {H1
1f8c0 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 3000} <H13010>.*
1f8d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
1f8e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
1f8f0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
1f900 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
1f910 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
1f920 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
1f930 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
1f940 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 statement..** Th
1f950 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 is object is var
1f960 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 iously known as
1f970 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 a "prepared stat
1f980 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 ement" or a.** "
1f990 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 compiled SQL sta
1f9a0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c tement" or simpl
1f9b0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e y as a "statemen
1f9c0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 t"..**.** The li
1f9d0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e fe of a statemen
1f9e0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f t object goes so
1f9f0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 mething like thi
1fa00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
1fa10 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 <li> Create the
1fa20 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
1fa30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1fa40 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 2()] or a relate
1fa50 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 d.** functi
1fa60 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 on..** <li> Bind
1fa70 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 values to [host
1fa80 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 parameters] usi
1fa90 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
1faa0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 ind_*().**
1fab0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c interfaces..** <
1fac0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 li> Run the SQL
1fad0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
1fae0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 te3_step()] one
1faf0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a or more times..*
1fb00 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 * <li> Reset the
1fb10 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
1fb20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1fb30 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a )] then go back.
1fb40 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 ** to step
1fb50 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 2. Do this zero
1fb60 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
1fb70 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 ** <li> Destroy
1fb80 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
1fb90 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1fba0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a ze()]..** </ol>.
1fbb0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 **.** Refer to d
1fbc0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 ocumentation on
1fbd0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f individual metho
1fbe0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 ds above for add
1fbf0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
1fc00 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 mation..*/.typed
1fc10 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1fc20 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 3_stmt sqlite3_s
1fc30 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tmt;../*.** CAPI
1fc40 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 3REF: Run-time L
1fc50 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c imits {H12760} <
1fc60 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20600>.**.** Th
1fc70 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
1fc80 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ows the size of
1fc90 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 various construc
1fca0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 ts to be limited
1fcb0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 .** on a connect
1fcc0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f ion by connectio
1fcd0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 n basis. The fi
1fce0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
1fcf0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
1fd00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 e connection] wh
1fd10 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 ose limit is to
1fd20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 be set or querie
1fd30 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e d. The.** secon
1fd40 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f d parameter is o
1fd50 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 ne of the [limit
1fd60 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 categories] tha
1fd70 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c t define a.** cl
1fd80 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 ass of construct
1fd90 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d s to be size lim
1fda0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 ited. The third
1fdb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1fdc0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 e.** new limit f
1fdd0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 or that construc
1fde0 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e t. The function
1fdf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 returns the old
1fe00 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 limit..**.** If
1fe10 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 the new limit i
1fe20 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d s a negative num
1fe30 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 ber, the limit i
1fe40 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 s unchanged..**
1fe50 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 For the limit ca
1fe60 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 tegory of SQLITE
1fe70 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 _LIMIT_XYZ there
1fe80 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72 is a hard upper
1fe90 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 .** bound set by
1fea0 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 a compile-time
1feb0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
1fec0 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 acro named SQLIT
1fed0 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 E_MAX_XYZ..** (T
1fee0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 he "_LIMIT_" in
1fef0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e the name is chan
1ff00 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 ged to "_MAX_".)
1ff10 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 .** Attempts to
1ff20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 increase a limit
1ff30 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 above its hard
1ff40 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a upper bound are.
1ff50 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e ** silently trun
1ff60 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 cated to the har
1ff70 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a d upper limit..*
1ff80 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 *.** Run time li
1ff90 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 mits are intende
1ffa0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 d for use in app
1ffb0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d lications that m
1ffc0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 anage.** both th
1ffd0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c eir own internal
1ffe0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c database and al
1fff0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 so databases tha
20000 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 t are controlled
20010 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 .** by untrusted
20020 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
20030 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 s. An example a
20040 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
20050 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 be a.** webbrow
20060 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 ser that has its
20070 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 own databases f
20080 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f or storing histo
20090 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 ry and.** separa
200a0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e te databases con
200b0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 trolled by JavaS
200c0 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f cript applicatio
200d0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a ns downloaded.**
200e0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 off the Interne
200f0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c t. The internal
20100 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 databases can b
20110 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c e given the.** l
20120 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 arge, default li
20130 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 mits. Databases
20140 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 managed by exte
20150 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e rnal sources can
20160 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 .** be given muc
20170 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 h smaller limits
20180 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 designed to pre
20190 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 vent a denial of
201a0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 service.** atta
201b0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 ck. Developers
201c0 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 might also want
201d0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 to use the [sqli
201e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
201f0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 er()].** interfa
20200 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f ce to further co
20210 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 ntrol untrusted
20220 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f SQL. The size o
20230 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
20240 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 * created by an
20250 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 untrusted script
20260 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 can be containe
20270 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b d using the.** [
20280 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
20290 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 [PRAGMA]..**.**
202a0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d New run-time lim
202b0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 it categories ma
202c0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
202d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
202e0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
202f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 .**.** {H12762}
20300 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
20310 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 l to [sqlite3_li
20320 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 mit(D,C,V)] wher
20330 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 e V is.**
20340 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e positive chan
20350 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e ges the limit on
20360 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e the size of con
20370 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a struct C in the.
20380 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 ** [dat
20390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
203a0 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65 ] D to the lesse
203b0 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 r of V and the h
203c0 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 ard upper.**
203d0 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 bound on t
203e0 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61 he size of C tha
203f0 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 t is set at comp
20400 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ile-time..**.**
20410 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 {H12766} A succe
20420 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
20430 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 qlite3_limit(D,C
20440 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 ,V)] where V is
20450 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 negative.**
20460 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 leaves the
20470 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61 state of the [da
20480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20490 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a n] D unchanged..
204a0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 **.** {H12769} A
204b0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
204c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d to [sqlite3_lim
204d0 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 it(D,C,V)] retur
204e0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ns the.**
204f0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 value of the
20500 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a limit on the siz
20510 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 e of construct C
20520 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 in the.**
20530 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
20540 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 nnection] D as i
20550 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 t was prior to t
20560 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 he call..*/.int
20570 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 sqlite3_limit(sq
20580 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 lite3*, int id,
20590 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a int newVal);../*
205a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
205b0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 n-Time Limit Cat
205c0 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d egories {H12790}
205d0 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 <H12760>.** KEY
205e0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 WORDS: {limit ca
205f0 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 tegory} {limit c
20600 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a ategories}.**.**
20610 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
20620 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
20630 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 aspects of a [da
20640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20650 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 n].** that can b
20660 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a e limited in siz
20670 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 e by calls to [s
20680 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
20690 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 .** The meanings
206a0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
206b0 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f limits are as fo
206c0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c llows:.**.** <dl
206d0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
206e0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 LIMIT_LENGTH</dt
206f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
20700 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 imum size of any
20710 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 string or BLOB
20720 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 or table row.<dd
20730 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
20740 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
20750 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
20760 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
20770 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 th of an SQL sta
20780 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a tement.</dd>.**.
20790 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
207a0 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a MIT_COLUMN</dt>.
207b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
207c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c um number of col
207d0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 umns in a table
207e0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e definition or in
207f0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 the.** result s
20800 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f et of a SELECT o
20810 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 r the maximum nu
20820 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
20830 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f in an index.** o
20840 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 r in an ORDER BY
20850 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 or GROUP BY cla
20860 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 use.</dd>.**.**
20870 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
20880 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e _EXPR_DEPTH</dt>
20890 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
208a0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 mum depth of the
208b0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 parse tree on a
208c0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f ny expression.</
208d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
208e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
208f0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a UND_SELECT</dt>.
20900 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
20910 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 um number of ter
20920 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 ms in a compound
20930 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
20940 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 t.</dd>.**.** <d
20950 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
20960 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
20970 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
20980 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
20990 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
209a0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
209b0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
209c0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
209d0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a tatement.</dd>.*
209e0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
209f0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
20a00 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 RG</dt>.** <dd>T
20a10 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
20a20 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f r of arguments o
20a30 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 n a function.</d
20a40 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
20a50 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
20a60 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
20a70 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
20a80 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61 r of attached da
20a90 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a tabases.</dd>.**
20aa0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
20ab0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
20ac0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a N_LENGTH</dt>.**
20ad0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
20ae0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 length of the p
20af0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 attern argument
20b00 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a to the LIKE or.*
20b10 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 * GLOB operators
20b20 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
20b30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
20b40 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
20b50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
20b60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
20b70 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 variables in an
20b80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
20b90 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 at can.** be bou
20ba0 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c nd.</dd>.** </dl
20bb0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
20bc0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
20bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20be0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
20bf0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
20c00 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
20c10 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
20c20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
20c30 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MN
20c40 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
20c50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
20c60 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 R_DEPTH
20c70 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
20c80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
20c90 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 MPOUND_SELECT
20ca0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
20cb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
20cc0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 DBE_OP
20cd0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
20ce0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
20cf0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 FUNCTION_ARG
20d00 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
20d10 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
20d20 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 _ATTACHED
20d30 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
20d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
20d50 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
20d60 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 ENGTH 8.#d
20d70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
20d80 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
20d90 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a ER 9..
20da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
20db0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
20dc0 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 Statement {H130
20dd0 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 10} <S10000>.**
20de0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 KEYWORDS: {SQL s
20df0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
20e00 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 r}.**.** To exec
20e10 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 ute an SQL query
20e20 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 , it must first
20e30 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f be compiled into
20e40 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 a byte-code.**
20e50 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e program using on
20e60 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
20e70 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nes..**.** The f
20e80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 irst argument, "
20e90 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 db", is a [datab
20ea0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
20eb0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a obtained from a.
20ec0 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f ** prior call to
20ed0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
20ee0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
20ef0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
20f00 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a e3_open16()]..**
20f10 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
20f20 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
20f30 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
20f40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
20f50 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
20f60 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
20f70 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
20f80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
20f90 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
20fa0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
20fb0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
20fc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
20fd0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
20fe0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
20ff0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
21000 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6..**.** If the
21010 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
21020 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f s less than zero
21030 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 , then zSql is r
21040 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a ead up to the.**
21050 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
21060 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 inator. If nByte
21070 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
21080 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
21090 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 maximum.** numb
210a0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 er of bytes rea
210b0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 d from zSql. Wh
210c0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d en nByte is non-
210d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a negative, the.**
210e0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 zSql string end
210f0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 s at either the
21100 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 first '\000' or
21110 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 '\u0000' charact
21120 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 er or.** the nBy
21130 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 te-th byte, whic
21140 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
21150 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 t. If the caller
21160 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 knows.** that t
21170 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
21180 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
21190 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 ated, then there
211a0 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 is a small.** p
211b0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
211c0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 tage to be gaine
211d0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 d by passing an
211e0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
211f0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c that.** is equal
21200 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f to the number o
21210 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
21220 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
21230 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
21240 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
21250 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 or bytes..**.**
21260 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 *pzTail is made
21270 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 to point to the
21280 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 first byte past
21290 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a the end of the.*
212a0 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 * first SQL stat
212b0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 ement in zSql.
212c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
212d0 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 nly compile the
212e0 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 first.** stateme
212f0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a nt in zSql, so *
21300 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 pzTail is left p
21310 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 ointing to what
21320 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d remains.** uncom
21330 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 piled..**.** *pp
21340 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 Stmt is left poi
21350 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 nting to a compi
21360 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 led [prepared st
21370 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 atement] that ca
21380 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 n be.** executed
21390 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
213a0 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 step()]. If the
213b0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
213c0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
213d0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 * to NULL. If t
213e0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
213f0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
21400 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 f the input is a
21410 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e n empty.** strin
21420 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 g or a comment)
21430 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 then *ppStmt is
21440 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 set to NULL..**
21450 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c {A13018} The cal
21460 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 ling procedure i
21470 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
21480 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
21490 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 ompiled.** SQL s
214a0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
214b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
214c0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
214d0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
214e0 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 t..**.** On succ
214f0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ess, [SQLITE_OK]
21500 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 is returned, ot
21510 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
21520 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
21530 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
21540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
21550 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 2() and sqlite3_
21560 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 prepare16_v2() i
21570 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a nterfaces are.**
21580 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
21590 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d all new program
215a0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 s. The two older
215b0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
215c0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 retained.** for
215d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
215e0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 ibility, but the
215f0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 ir use is discou
21600 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 raged..** In the
21610 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
21620 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
21630 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
21640 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
21650 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
21660 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
21670 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
21680 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
21690 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
216a0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
216b0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
216c0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 to.** behave a
216d0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
216e0 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c wo ways:.**.** <
216f0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 ol>.** <li>.** I
21700 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 f the database s
21710 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 chema changes, i
21720 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e nstead of return
21730 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 ing [SQLITE_SCHE
21740 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 MA] as it.** alw
21750 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 ays used to do,
21760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21770 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
21780 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 lly recompile th
21790 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 e SQL.** stateme
217a0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 nt and try to ru
217b0 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 n it again. If
217c0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 the schema has c
217d0 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 hanged in.** a w
217e0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 ay that makes th
217f0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c e statement no l
21800 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 onger valid, [sq
21810 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
21820 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 ll still.** retu
21830 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d rn [SQLITE_SCHEM
21840 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 A]. But unlike
21850 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
21860 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 ior, [SQLITE_SCH
21870 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 EMA] is.** now a
21880 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 fatal error. C
21890 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
218a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 prepare_v2()] ag
218b0 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b ain will not mak
218c0 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 e the.** error g
218d0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 o away. Note: u
218e0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d se [sqlite3_errm
218f0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 sg()] to find th
21900 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 e text.** of the
21910 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 parsing error t
21920 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 hat results in a
21930 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
21940 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c ] return..** </l
21950 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
21960 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f When an error o
21970 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
21980 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
21990 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
219a0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
219b0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
219c0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
219d0 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 s]. The legacy
219e0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
219f0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
21a00 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
21a10 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
21a20 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
21a30 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
21a40 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 and you would ha
21a50 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 ve to make a sec
21a60 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ond call to [sql
21a70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e ite3_reset()] in
21a80 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e order.** to fin
21a90 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
21aa0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 cause of the pr
21ab0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 oblem. With the
21ac0 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 "v2" prepare.**
21ad0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
21ae0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f underlying reaso
21af0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 n for the error
21b00 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
21b10 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 diately..** </li
21b20 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a >.** </ol>.**.**
21b30 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
21b40 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20 ** {H13011} The
21b50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
21b60 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 (db,zSql,...)] a
21b70 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b nd.** [
21b80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21b90 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d v2(db,zSql,...)]
21ba0 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 interfaces inte
21bb0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 rpret the.**
21bc0 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 text in th
21bd0 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 eir zSql paramet
21be0 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a er as UTF-8..**.
21bf0 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20 ** {H13012} The
21c00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
21c10 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 16(db,zSql,...)]
21c20 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
21c30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21c40 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e e16_v2(db,zSql,.
21c50 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 ..)] interfaces
21c60 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a interpret the.**
21c70 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69 text i
21c80 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 n their zSql par
21c90 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 ameter as UTF-16
21ca0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
21cb0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a yte order..**.**
21cc0 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65 {H13013} If the
21cd0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
21ce0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
21cf0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e are_v2(db,zSql,n
21d00 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 Byte,...)].**
21d10 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 and its v
21d20 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 ariants is less
21d30 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 than zero, the S
21d40 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 QL text is.**
21d50 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d read from
21d60 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
21d70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
21d80 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ro terminator..*
21d90 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 *.** {H13014} If
21da0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
21db0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
21dc0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 prepare_v2(db,zS
21dd0 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a ql,nByte,...)].*
21de0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 * and i
21df0 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e ts variants is n
21e00 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
21e10 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 n at most nBytes
21e20 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 bytes of.**
21e30 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 SQL text i
21e40 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
21e50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d ..**.** {H13015}
21e60 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 In [sqlite3_pre
21e70 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c pare_v2(db,zSql,
21e80 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 N,P,pzTail)] and
21e90 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a its variants.**
21ea0 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 if the
21eb0 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 zSql input text
21ec0 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 contains more t
21ed0 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 han one SQL stat
21ee0 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 ement.**
21ef0 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 and pzTail is
21f00 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a not NULL, then *
21f10 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
21f20 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a o point to the.*
21f30 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 * first
21f40 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 byte past the e
21f50 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
21f60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
21f70 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 zSql..**
21f80 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f <todo>What do
21f90 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 es *pzTail point
21fa0 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 to if there is
21fb0 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f one statement?</
21fc0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 todo>.**.** {H13
21fd0 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 016} A successfu
21fe0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
21ff0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 e3_prepare_v2(db
22000 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e ,zSql,N,ppStmt,.
22010 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
22020 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 or one of its v
22030 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 ariants writes i
22040 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f nto *ppStmt a po
22050 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a inter to a new.*
22060 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
22070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
22080 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 or a pointer to
22090 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e NULL if zSql con
220a0 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 tains.**
220b0 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 nothing other
220c0 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 than whitespace
220d0 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a or comments..**.
220e0 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20 ** {H13019} The
220f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
22100 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
22110 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
22120 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 s return.**
22130 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d [SQLITE_OK]
22140 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 or an appropria
22150 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 te [error code]
22160 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a upon failure..**
22170 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66 .** {H13021} Bef
22180 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ore [sqlite3_pre
22190 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 pare(db,zSql,nBy
221a0 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c te,ppStmt,pzTail
221b0 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 )] or its.**
221c0 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72 variants r
221d0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 eturns an error
221e0 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 (any value other
221f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
22200 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ]),.**
22210 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a they first set *
22220 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a ppStmt to NULL..
22230 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 */.int sqlite3_p
22240 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 repare(. sqlite
22250 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
22260 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
22270 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
22280 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
22290 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
222a0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
222b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
222c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
222d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
222e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
222f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
22300 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
22310 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
22320 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
22330 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
22340 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
22350 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
22360 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
22370 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
22380 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 3_prepare_v2(.
22390 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
223a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
223b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
223c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
223d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
223e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 tatement, UTF-8
223f0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
22400 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
22410 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
22420 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
22430 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
22440 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
22450 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
22460 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
22470 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
22480 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
22490 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
224a0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
224b0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
224c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
224d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
224e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
224f0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
22500 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
22510 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
22520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
22530 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
22540 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
22550 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
22560 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
22570 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
22580 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
22590 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
225a0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
225b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
225c0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
225d0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
225e0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
225f0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
22600 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
22610 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 epare16_v2(. sq
22620 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
22630 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
22640 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
22650 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
22660 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
22670 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
22680 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
22690 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
226a0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
226b0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
226c0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
226d0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
226e0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
226f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
22700 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
22710 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
22720 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
22730 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
22740 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a zSql */.);../*.*
22750 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 * CAPI3REF: Retr
22760 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 ieving Statement
22770 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 SQL {H13100} <H
22780 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 13000>.**.** Thi
22790 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
227a0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 be used to retri
227b0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 eve a saved copy
227c0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c of the original
227d0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 .** SQL text use
227e0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 d to create a [p
227f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
22800 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 t] if that state
22810 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 ment was.** comp
22820 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 iled using eithe
22830 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
22840 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
22850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
22860 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 2()]..**.** INVA
22870 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
22880 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 13101} If the [p
22890 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
228a0 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 t] passed as the
228b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
228c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
228d0 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 3_sql()] was com
228e0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 piled using eith
228f0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
22900 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 are_v2()] or.**
22910 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
22920 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
22930 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ], then [sqlite3
22940 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a _sql()] returns.
22950 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f ** a po
22960 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d inter to a zero-
22970 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
22980 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 g containing a U
22990 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a TF-8 rendering.*
229a0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 * of th
229b0 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 e original SQL s
229c0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
229d0 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 {H13102} If the
229e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
229f0 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 ent] passed as t
22a00 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
22a10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
22a20 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 te3_sql()] was c
22a30 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 ompiled using ei
22a40 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
22a50 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 epare()] or.**
22a60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
22a70 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 _prepare16()], t
22a80 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c hen [sqlite3_sql
22a90 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 ()] returns a NU
22aa0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
22ab0 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73 * {H13103} The s
22ac0 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 tring returned b
22ad0 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 y [sqlite3_sql(S
22ae0 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 )] is valid unti
22af0 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 l the.**
22b00 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
22b10 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 ement] S is dele
22b20 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
22b30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e e3_finalize(S)].
22b40 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
22b50 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
22b60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
22b70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
22b80 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 F: Dynamically T
22b90 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 yped Value Objec
22ba0 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 t {H15000} <S202
22bb0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
22bc0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 {protected sqli
22bd0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 te3_value} {unpr
22be0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
22bf0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c value}.**.** SQL
22c00 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c ite uses the sql
22c10 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
22c20 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 t to represent a
22c30 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 ll values.** tha
22c40 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 t can be stored
22c50 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 in a database ta
22c60 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 ble. SQLite uses
22c70 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a dynamic typing.
22c80 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 ** for the value
22c90 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c s it stores. Val
22ca0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 ues stored in sq
22cb0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
22cc0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e cts.** can be in
22cd0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 tegers, floating
22ce0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 point values, s
22cf0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f trings, BLOBs, o
22d00 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e r NULL..**.** An
22d10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
22d20 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 bject may be eit
22d30 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 her "protected"
22d40 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 or "unprotected"
22d50 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 ..** Some interf
22d60 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 aces require a p
22d70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
22d80 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 _value. Other i
22d90 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c nterfaces.** wil
22da0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 l accept either
22db0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 a protected or a
22dc0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
22dd0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 lite3_value..**
22de0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 Every interface
22df0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c that accepts sql
22e00 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d ite3_value argum
22e10 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a ents specifies.*
22e20 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * whether or not
22e30 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 it requires a p
22e40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
22e50 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 _value..**.** Th
22e60 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 e terms "protect
22e70 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 ed" and "unprote
22e80 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 cted" refer to w
22e90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a hether or not.**
22ea0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 a mutex is held
22eb0 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 . A internal mu
22ec0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
22ed0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 a protected.** s
22ee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
22ef0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 ect but no mutex
22f00 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 is held for an
22f10 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
22f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
22f30 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 ect. If SQLite
22f40 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 is compiled to b
22f50 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 e single-threade
22f60 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 d.** (with [SQLI
22f70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
22f80 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 and with [sqlit
22f90 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
22fa0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a returning 0).**
22fb0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 or if SQLite is
22fc0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 run in one of r
22fd0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 educed mutex mod
22fe0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 es .** [SQLITE_C
22ff0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
23000 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 AD] or [SQLITE_C
23010 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
23020 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 D].** then there
23030 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 is no distincti
23040 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
23050 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
23060 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
23070 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e value objects an
23080 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 d they can be us
23090 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 ed interchangeab
230a0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ly. However,.**
230b0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 for maximum cod
230c0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 e portability it
230d0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
230e0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
230f0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 s.** still make
23100 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 the distinction
23110 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 between between
23120 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
23130 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
23140 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
23150 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 ts even when not
23160 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 strictly requir
23170 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
23180 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
23190 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 cts that are pas
231a0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 sed as parameter
231b0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d s into the.** im
231c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
231d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
231e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
231f0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 ns] are protecte
23200 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 d..** The sqlite
23210 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
23220 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
23230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
23240 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
23250 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
23260 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
23270 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
23280 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
23290 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 h.** [sqlite3_re
232a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e sult_value()] an
232b0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
232c0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 value()]..** The
232d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
232e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
232f0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
23300 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
23310 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
23320 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
23330 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
23340 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
23350 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 Mem sqlite3_valu
23360 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
23370 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e EF: SQL Function
23380 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 Context Object
23390 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 {H16001} <S20200
233a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 >.**.** The cont
233b0 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 ext in which an
233c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 SQL function exe
233d0 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 cutes is stored
233e0 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 in an.** sqlite3
233f0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e _context object.
23400 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 A pointer to a
23410 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 n sqlite3_contex
23420 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 t object.** is a
23430 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 lways first para
23440 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 meter to [applic
23450 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
23460 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a L functions]..**
23470 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
23480 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
23490 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
234a0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 tion will pass t
234b0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 his.** pointer t
234c0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c hrough into call
234d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 s to [sqlite3_re
234e0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 sult_int | sqlit
234f0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a e3_result()],.**
23500 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 [sqlite3_aggreg
23510 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 ate_context()],
23520 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
23530 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ta()],.** [sqlit
23540 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
23550 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ndle()], [sqlite
23560 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_get_auxdata()]
23570 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c ,.** and/or [sql
23580 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
23590 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
235a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 struct sqlite3_c
235b0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 ontext sqlite3_c
235c0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ontext;../*.** C
235d0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 API3REF: Binding
235e0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 Values To Prepa
235f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b red Statements {
23600 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e H13500} <S70300>
23610 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
23620 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
23630 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
23640 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
23650 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
23660 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
23670 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
23680 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
23690 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 binding}.**.** I
236a0 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 n the SQL string
236b0 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 s input to [sqli
236c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
236d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
236e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
236f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
23700 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 by a parameter i
23710 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 n one of these f
23720 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e orms:.**.** <ul>
23730 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c .** <li> ?.** <
23740 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 li> ?NNN.** <li
23750 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > :VVV.** <li>
23760 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 @VVV.** <li> $
23770 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VVV.** </ul>.**.
23780 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 ** In the parame
23790 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 ter forms shown
237a0 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 above NNN is an
237b0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c integer literal,
237c0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 .** and VVV is a
237d0 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 n alpha-numeric
237e0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 parameter name.
237f0 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
23800 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ese.** parameter
23810 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
23820 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
23830 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 ames" or "SQL pa
23840 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 rameters").** ca
23850 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 n be set using t
23860 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
23870 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 *() routines def
23880 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ined here..**.**
23890 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
238a0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
238b0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
238c0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
238d0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
238e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
238f0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
23900 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
23910 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
23920 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
23930 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
23940 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
23950 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
23960 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
23970 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 be set..** The
23980 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
23990 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
239a0 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 dex of 1. When
239b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
239c0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
239d0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
239e0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
239f0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
23a00 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
23a10 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
23a20 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
23a30 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 currence..** The
23a40 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
23a50 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
23a60 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
23a70 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
23a80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
23a90 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 r_index()] API i
23aa0 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 f desired. The
23ab0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e index.** for "?N
23ac0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 NN" parameters i
23ad0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e s the value of N
23ae0 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 NN..** The NNN v
23af0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
23b00 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
23b10 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
23b20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
23b30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
23b40 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
23b50 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
23b60 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 )..**.** The thi
23b70 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
23b80 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 he value to bind
23b90 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
23ba0 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 r..**.** In thos
23bb0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
23bc0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
23bd0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
23be0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
23bf0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
23c00 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
23c10 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
23c20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
23c30 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
23c40 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
23c50 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
23c60 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
23c70 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 s..** If the fou
23c80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
23c90 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c negative, the l
23ca0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 ength of the str
23cb0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 ing is.** the nu
23cc0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 mber of bytes up
23cd0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
23ce0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ro terminator..*
23cf0 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 *.** The fifth a
23d00 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
23d10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 e3_bind_blob(),
23d20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
23d30 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 t(), and.** sqli
23d40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
23d50 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f ) is a destructo
23d60 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 r used to dispos
23d70 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
23d80 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 .** string after
23d90 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 SQLite has fini
23da0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 shed with it. If
23db0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
23dc0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 ent is.** the sp
23dd0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c ecial value [SQL
23de0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 ITE_STATIC], the
23df0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 n SQLite assumes
23e00 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 that the.** inf
23e10 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 ormation is in s
23e20 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 tatic, unmanaged
23e30 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
23e40 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 not need to be f
23e50 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 reed..** If the
23e60 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
23e70 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
23e80 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
23e90 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
23ea0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
23eb0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
23ec0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
23ed0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
23ee0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
23ef0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
23f00 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ns..**.** The sq
23f10 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
23f20 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 lob() routine bi
23f30 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 nds a BLOB of le
23f40 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 ngth N that.** i
23f50 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 s filled with ze
23f60 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f roes. A zeroblo
23f70 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 b uses a fixed a
23f80 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a mount of memory.
23f90 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 ** (just an inte
23fa0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 ger to hold its
23fb0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
23fc0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
23fd0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
23fe0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
23ff0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f serve as placeho
24000 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 lders for BLOBs
24010 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 whose.** content
24020 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 is later writte
24030 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
24040 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
24050 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
24060 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a I/O] routines..
24070 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 ** A negative va
24080 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
24090 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
240a0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
240b0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 OB..**.** The sq
240c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
240d0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
240e0 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 called after.**
240f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
24100 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 _v2()] (and its
24110 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 variants) or [sq
24120 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 lite3_reset()] a
24130 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 nd.** before [sq
24140 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
24150 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e * Bindings are n
24160 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 ot cleared by th
24170 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
24180 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 ()] routine..**
24190 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 Unbound paramete
241a0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 rs are interpret
241b0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ed as NULL..**.*
241c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
241d0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
241e0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
241f0 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 r an error code
24200 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 if.** anything g
24210 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c oes wrong. [SQL
24220 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
24230 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
24240 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
24250 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
24260 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d . [SQLITE_NOMEM
24270 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
24280 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e malloc() fails.
24290 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
242a0 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 SE] might be ret
242b0 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 urned if these r
242c0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
242d0 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 ed on a.** virtu
242e0 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 al machine that
242f0 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 is the wrong sta
24300 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 te or which has
24310 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e already been fin
24320 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 alized..** Detec
24330 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 tion of misuse i
24340 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 s unreliable. A
24350 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
24360 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a ld not depend.**
24370 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 on SQLITE_MISUS
24380 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 E returns. SQLI
24390 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 TE_MISUSE is int
243a0 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 ended to indicat
243b0 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 e a.** a logic e
243c0 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c rror in the appl
243d0 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 ication. Future
243e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
243f0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e ite might.** pan
24400 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 ic rather than r
24410 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 eturn SQLITE_MIS
24420 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 USE..**.** See a
24430 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
24440 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
24450 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nt()],.** [sqlit
24460 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
24470 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b r_name()], and [
24480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
24490 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
244a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
244b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 S:.**.** {H13506
244c0 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 } The [SQL state
244d0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 ment compiler] r
244e0 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 ecognizes tokens
244f0 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a of the forms.**
24500 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 "?", "
24510 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 ?NNN", "$VVV", "
24520 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 :VVV", and "@VVV
24530 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 " as SQL paramet
24540 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ers,.**
24550 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e where NNN is an
24560 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e y sequence of on
24570 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 e or more digits
24580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
24590 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e where VVV is an
245a0 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e y sequence of on
245b0 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e e or more alphan
245c0 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 umeric.**
245d0 20 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 characters or
245e0 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 "::" optionally
245f0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 followed by a s
24600 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
24610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 .** no
24620 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 spaces and conta
24630 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 ined within pare
24640 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b ntheses..**.** {
24650 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 H13509} The init
24660 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 ial value of an
24670 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
24680 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 NULL..**.** {H1
24690 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 3512} The index
246a0 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 of an "?" SQL pa
246b0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c rameter is one l
246c0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a arger than the.*
246d0 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 * large
246e0 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 st index of SQL
246f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
24700 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a left, or 1 if.*
24710 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22 * the "
24720 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f ?" is the leftmo
24730 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
24740 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d ..**.** {H13515}
24750 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e The index of an
24760 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 "?NNN" SQL para
24770 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 meter is the int
24780 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 eger NNN..**.**
24790 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 {H13518} The ind
247a0 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c ex of an ":VVV",
247b0 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 "$VVV", or "@VV
247c0 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 V" SQL parameter
247d0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
247e0 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 the same as the
247f0 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 index of leftmos
24800 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 t occurrences of
24810 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
24820 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c parameter,
24830 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 or one more tha
24840 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e n the largest in
24850 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 dex over all.**
24860 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 paramet
24870 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 ers to the left
24880 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66 if this is the f
24890 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a irst occurrence.
248a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 ** of t
248b0 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f his parameter, o
248c0 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74 r 1 if this is t
248d0 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 he leftmost para
248e0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 meter..**.** {H1
248f0 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 3521} The [SQL s
24900 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
24910 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e r] fails with an
24920 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a [SQLITE_RANGE].
24930 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f ** erro
24940 72 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f r if the index o
24950 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 f an SQL paramet
24960 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 er is less than
24970 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 1.** or
24980 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
24990 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 e compile-time S
249a0 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 QLITE_MAX_VARIAB
249b0 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 LE_NUMBER.**
249c0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e parameter.
249d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 .**.** {H13524}
249e0 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 Calls to [sqlite
249f0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 3_bind_text | sq
24a00 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 lite3_bind(S,N,V
24a10 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,...)].**
24a20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 associate the
24a30 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c value V with al
24a40 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 l SQL parameters
24a50 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 having an.**
24a60 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 index of
24a70 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 N in the [prepar
24a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e ed statement] S.
24a90 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 .**.** {H13527}
24aa0 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 Calls to [sqlite
24ab0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 3_bind_text | sq
24ac0 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e lite3_bind(S,N,.
24ad0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
24ae0 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 override prior
24af0 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 calls with the s
24b00 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 ame values of S
24b10 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 and N..**.** {H1
24b20 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 3530} Bindings e
24b30 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 stablished by [s
24b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
24b50 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 | sqlite3_bind(
24b60 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 S,...)].**
24b70 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f persist acro
24b80 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ss calls to [sql
24b90 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a ite3_reset(S)]..
24ba0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 **.** {H13533} I
24bb0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 n calls to [sqli
24bc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c te3_bind_blob(S,
24bd0 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 N,V,L,D)],.**
24be0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
24bf0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c bind_text(S,N,V,
24c00 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 L,D)], or.**
24c10 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
24c20 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 ind_text16(S,N,V
24c30 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 ,L,D)] SQLite bi
24c40 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a nds the first L.
24c50 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 ** byte
24c60 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 s of the BLOB or
24c70 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 string pointed
24c80 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a to by V, when L.
24c90 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e ** is n
24ca0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a on-negative..**.
24cb0 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 ** {H13536} In c
24cc0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
24cd0 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 _bind_text(S,N,V
24ce0 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 ,L,D)] or.**
24cf0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
24d00 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 ind_text16(S,N,V
24d10 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 ,L,D)] SQLite bi
24d20 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a nds characters.*
24d30 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 * from
24d40 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 V through the fi
24d50 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
24d60 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 er when L is neg
24d70 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
24d80 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3539} In calls t
24d90 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
24da0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d blob(S,N,V,L,D)]
24db0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
24dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
24dd0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 (S,N,V,L,D)], or
24de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
24df0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
24e00 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 6(S,N,V,L,D)] wh
24e10 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 en D is the spec
24e20 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ial.**
24e30 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 constant [SQLITE
24e40 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 _STATIC], SQLite
24e50 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
24e60 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 e value V.**
24e70 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e is held in
24e80 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 static unmanage
24e90 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c d space that wil
24ea0 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 l not change.**
24eb0 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 during
24ec0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 the lifetime of
24ed0 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a the binding..**.
24ee0 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 ** {H13542} In c
24ef0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
24f00 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 _bind_blob(S,N,V
24f10 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,L,D)],.**
24f20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e [sqlite3_bin
24f30 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 d_text(S,N,V,L,D
24f40 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 )], or.**
24f50 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
24f60 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
24f70 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 D)] when D is th
24f80 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 e special.**
24f90 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b constant [
24fa0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
24fb0 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d ], the routine m
24fc0 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 akes a.**
24fd0 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 private copy
24fe0 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 of the value V b
24ff0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
25000 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d ..**.** {H13545}
25010 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 In calls to [sq
25020 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
25030 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 S,N,V,L,D)],.**
25040 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
25050 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 3_bind_text(S,N,
25060 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 V,L,D)], or.**
25070 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
25080 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e _bind_text16(S,N
25090 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 ,V,L,D)] when D
250a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a is a pointer to.
250b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 ** a fu
250c0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 nction, SQLite i
250d0 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 nvokes that func
250e0 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 tion to destroy
250f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
25100 76 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 value V after it
25110 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
25120 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e ing the value V.
25130 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 .**.** {H13548}
25140 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
25150 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
25160 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 ob(S,N,V,L)] the
25170 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 value bound.**
25180 20 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c is a BL
25190 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f OB of L bytes, o
251a0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
251b0 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 BLOB if L is neg
251c0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
251d0 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3551} In calls t
251e0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
251f0 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 value(S,N,V)] th
25200 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 e V argument may
25210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 .** be
25220 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 either a [protec
25230 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
25240 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a e] object or an.
25250 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 ** [unp
25260 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
25270 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a _value] object..
25280 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
25290 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 ind_blob(sqlite3
252a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
252b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c st void*, int n,
252c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
252d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
252e0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 nd_double(sqlite
252f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 3_stmt*, int, do
25300 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 uble);.int sqlit
25310 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 e3_bind_int(sqli
25320 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
25330 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
25340 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 3_bind_int64(sql
25350 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
25360 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
25370 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
25380 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 d_null(sqlite3_s
25390 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 tmt*, int);.int
253a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
253b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
253c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 int, const char
253d0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
253e0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
253f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
25400 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
25410 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
25420 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
25430 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
25440 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
25450 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
25460 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 int, const sqlit
25470 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
25480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
25490 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 oblob(sqlite3_st
254a0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 mt*, int, int n)
254b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
254c0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c F: Number Of SQL
254d0 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 Parameters {H13
254e0 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 600} <S70300>.**
254f0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
25500 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
25510 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
25520 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 of [SQL paramete
25530 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 rs].** in a [pre
25540 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
25550 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 . SQL parameter
25560 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 s are tokens of
25570 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c the.** form "?",
25580 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c "?NNN", ":AAA",
25590 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 "$AAA", or "@AA
255a0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 A" that serve as
255b0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 .** placeholders
255c0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 for values that
255d0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 are [sqlite3_bi
255e0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d nd_blob | bound]
255f0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d .** to the param
25600 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 eters at a later
25610 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 time..**.** Thi
25620 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c s routine actual
25630 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 ly returns the i
25640 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 ndex of the larg
25650 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a est (rightmost).
25660 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f ** parameter. Fo
25670 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 r all forms exce
25680 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 pt ?NNN, this wi
25690 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f ll correspond to
256a0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
256b0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 f unique paramet
256c0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 ers. If paramet
256d0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 ers of the ?NNN
256e0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 are used,.** the
256f0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 re may be gaps i
25700 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a n the list..**.*
25710 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
25720 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
25730 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
25740 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
25750 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
25760 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
25770 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
25780 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a er_index()]..**.
25790 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
257a0 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 *.** {H13601} Th
257b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
257c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
257d0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
257e0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 turns.**
257f0 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e the largest in
25800 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 dex of all SQL p
25810 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 arameters in the
25820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
25830 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25840 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63 ] S, or 0 if S c
25850 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 ontains no SQL p
25860 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e arameters..*/.in
25870 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
25880 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 arameter_count(s
25890 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
258a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
258b0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 Name Of A Host P
258c0 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 arameter {H13620
258d0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
258e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
258f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
25900 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 to the name of t
25910 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 he n-th.** [SQL
25920 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 parameter] in a
25930 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
25940 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 ent]..** SQL par
25950 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
25960 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a orm "?NNN" or ":
25970 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
25980 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 r "$AAA".** have
25990 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 a name which is
259a0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e the string "?NN
259b0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
259c0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
259d0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
259e0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f ..** In other wo
259f0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c rds, the initial
25a00 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 ":" or "$" or "
25a10 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 @" or "?".** is
25a20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 included as part
25a30 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a of the name..**
25a40 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 Parameters of t
25a50 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
25a60 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
25a70 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
25a80 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
25a90 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f also referred to
25aa0 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 as "anonymous p
25ab0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a arameters"..**.*
25ac0 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 * The first host
25ad0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
25ae0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f n index of 1, no
25af0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 t 0..**.** If th
25b00 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 e value n is out
25b10 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 of range or if
25b20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 the n-th paramet
25b30 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 er is.** nameles
25b40 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 s, then NULL is
25b50 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 returned. The r
25b60 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
25b70 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 s.** always in U
25b80 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 TF-8 encoding ev
25b90 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 en if the named
25ba0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a parameter was.**
25bb0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 originally spec
25bc0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 ified as UTF-16
25bd0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 in [sqlite3_prep
25be0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b are16()] or.** [
25bf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
25c00 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
25c10 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
25c20 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
25c30 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
25c40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
25c50 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
25c60 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
25c70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
25c80 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a _index()]..**.**
25c90 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
25ca0 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20 ** {H13621} The
25cb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
25cc0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e rameter_name(S,N
25cd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
25ce0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
25cf0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 a UTF-8 renderi
25d00 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f ng of the name o
25d10 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 f the SQL parame
25d20 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 ter in.**
25d30 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 the [prepared
25d40 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 statement] S ha
25d50 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 ving index N, or
25d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c .** NUL
25d70 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f L if there is no
25d80 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 SQL parameter w
25d90 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 ith index N or i
25da0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
25db0 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 parameter with
25dc0 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 index N is an a
25dd0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 nonymous paramet
25de0 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 er "?"..*/.const
25df0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 char *sqlite3_b
25e00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
25e10 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
25e20 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , int);../*.** C
25e30 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f API3REF: Index O
25e40 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 f A Parameter Wi
25e50 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 th A Given Name
25e60 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 {H13640} <S70300
25e70 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 >.**.** Return t
25e80 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 he index of an S
25e90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 QL parameter giv
25ea0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 en its name. Th
25eb0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 e.** index value
25ec0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 returned is sui
25ed0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 table for use as
25ee0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 the second.** p
25ef0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
25f00 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
25f10 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 qlite3_bind()].
25f20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 A zero.** is re
25f30 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
25f40 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
25f50 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 is found. The p
25f60 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 arameter.** name
25f70 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 must be given i
25f80 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 n UTF-8 even if
25f90 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
25fa0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 tement.** was pr
25fb0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d epared from UTF-
25fc0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 16 text using [s
25fd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
25fe0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
25ff0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
26000 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
26010 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
26020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
26030 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
26040 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
26050 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
26060 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 index()]..**.**
26070 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
26080 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b * {H13641} The [
26090 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
260a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e ameter_index(S,N
260b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
260c0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
260d0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51 the index of SQ
260e0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 L parameter in t
260f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
26100 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 tement].**
26110 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 S whose name
26120 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46 matches the UTF
26130 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 -8 string N, or
26140 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 0 if there is.**
26150 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 no mat
26160 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ch..*/.int sqlit
26170 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
26180 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
26190 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
261a0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
261b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
261c0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
261d0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
261e0 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 tement {H13660}
261f0 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 <S70300>.**.** C
26200 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
26210 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
26220 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
26230 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
26240 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
26250 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
26260 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
26270 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
26280 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 t]..** Use this
26290 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 routine to reset
262a0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 all host parame
262b0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a ters to NULL..**
262c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
262d0 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 **.** {H13661} T
262e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 he [sqlite3_clea
262f0 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 r_bindings(S)] i
26300 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
26310 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 all SQL.**
26320 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69 parameter bi
26330 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 ndings in the [p
26340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
26350 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c t] S back to NUL
26360 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 L..*/.int sqlite
26370 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
26380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
26390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
263a0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 : Number Of Colu
263b0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mns In A Result
263c0 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 Set {H13710} <S1
263d0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 0700>.**.** Retu
263e0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
263f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
26400 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
26410 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
26420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
26430 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 t]. This routine
26440 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 returns 0 if pS
26450 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a tmt is an SQL.**
26460 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
26470 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 does not return
26480 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c data (for exampl
26490 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a e an [UPDATE])..
264a0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
264b0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d :.**.** {H13711}
264c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
264d0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 lumn_count(S)] i
264e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
264f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
26500 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d * colum
26510 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
26520 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 set generated b
26530 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 y the [prepared
26540 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a statement] S,.**
26550 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69 or 0 i
26560 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e f S does not gen
26570 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73 erate a result s
26580 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 et..*/.int sqlit
26590 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
265a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
265b0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
265c0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 I3REF: Column Na
265d0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mes In A Result
265e0 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 Set {H13720} <S1
265f0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0700>.**.** Thes
26600 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
26610 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 n the name assig
26620 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 ned to a particu
26630 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e lar column.** in
26640 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
26650 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 of a [SELECT] st
26660 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 atement. The sq
26670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
26680 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 e().** interface
26690 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
266a0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
266b0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
266c0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ring.** and sqli
266d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
266e0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 6() returns a po
266f0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d inter to a zero-
26700 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
26710 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 F-16 string. Th
26720 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
26730 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
26740 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
26750 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
26760 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
26770 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 atement. The sec
26780 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
26790 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e the.** column n
267a0 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 umber. The left
267b0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e most column is n
267c0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 umber 0..**.** T
267d0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
267e0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 ng pointer is va
267f0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 lid until either
26800 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
26810 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 tatement].** is
26820 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
26830 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
26840 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e ] or until the n
26850 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 ext call to.** s
26860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
26870 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f me() or sqlite3_
26880 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
26890 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
268a0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c mn..**.** If sql
268b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 ite3_malloc() fa
268c0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 ils during the p
268d0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 rocessing of eit
268e0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 her routine.** (
268f0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 for example duri
26900 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ng a conversion
26910 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 from UTF-8 to UT
26920 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 F-16) then a.**
26930 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
26940 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
26950 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 The name of a re
26960 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 sult column is t
26970 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
26980 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a "AS" clause for.
26990 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 ** that column,
269a0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 if there is an A
269b0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 S clause. If th
269c0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 ere is no AS cla
269d0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 use.** then the
269e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 name of the colu
269f0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 mn is unspecifie
26a00 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 d and may change
26a10 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c from.** one rel
26a20 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 ease of SQLite t
26a30 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a o the next..**.*
26a40 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
26a50 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73 .** {H13721} A s
26a60 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
26a70 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c tion of the [sql
26a80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
26a90 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 (S,N)].**
26aa0 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 interface ret
26ab0 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 urns the name of
26ac0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
26ad0 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 (where 0 is.**
26ae0 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 the left
26af0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 most column) for
26b00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
26b10 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
26b20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
26b30 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a tement] S as a z
26b40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
26b50 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a TF-8 string..**.
26b60 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75 ** {H13723} A su
26b70 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
26b80 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ion of the [sqli
26b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
26ba0 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 6(S,N)].**
26bb0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 interface re
26bc0 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f turns the name o
26bd0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
26be0 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 (where 0 is.**
26bf0 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 the lef
26c00 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f tmost column) fo
26c10 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 r the result set
26c20 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
26c30 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
26c40 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 atement] S as a
26c50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
26c60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a UTF-16 string.**
26c70 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 in the
26c80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
26c90 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 er..**.** {H1372
26ca0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 4} The [sqlite3_
26cb0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 column_name()] a
26cc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 nd [sqlite3_colu
26cd0 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 mn_name16()].**
26ce0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 interfa
26cf0 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c ces return a NUL
26d00 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 L pointer if the
26d10 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a y are unable to.
26d20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f ** allo
26d30 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 cate memory to h
26d40 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c old their normal
26d50 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e return strings.
26d60 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 .**.** {H13725}
26d70 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 If the N paramet
26d80 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 er to [sqlite3_c
26d90 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d olumn_name(S,N)]
26da0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
26db0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
26dc0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 name16(S,N)] is
26dd0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 out of range, th
26de0 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 en the.**
26df0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 interfaces re
26e00 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e turn a NULL poin
26e10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ter..**.** {H137
26e20 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 26} The strings
26e30 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
26e40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
26e50 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 (S,N)] and.**
26e60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
26e70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c column_name16(S,
26e80 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e N)] are valid un
26e90 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 til the next.**
26ea0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f call to
26eb0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 either routine
26ec0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 with the same S
26ed0 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 and N parameters
26ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
26ef0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 until [sqlite3_f
26f00 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 inalize(S)] is c
26f10 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 alled..**.** {H1
26f20 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 3727} When a res
26f30 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 ult column of a
26f40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
26f50 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 nt contains.**
26f60 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c an AS cl
26f70 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f ause, the name o
26f80 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 f that column is
26f90 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a the identifier.
26fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 ** to t
26fb0 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 he right of the
26fc0 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 AS keyword..*/.c
26fd0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
26fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 e3_column_name(s
26ff0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
27000 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 t N);.const void
27010 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
27020 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
27030 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a stmt*, int N);..
27040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27050 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 Source Of Data I
27060 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 n A Query Result
27070 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 {H13740} <S1070
27080 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 0>.**.** These r
27090 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 outines provide
270a0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 a means to deter
270b0 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e mine what column
270c0 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c of what.** tabl
270d0 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 e in which datab
270e0 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 ase a result of
270f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
27100 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e ment comes from.
27110 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
27120 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 the database or
27130 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 table or column
27140 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
27150 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 as.** either a U
27160 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 TF-8 or UTF-16 s
27170 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 tring. The _dat
27180 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 abase_ routines
27190 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 return.** the da
271a0 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 tabase name, the
271b0 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 _table_ routine
271c0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 s return the tab
271d0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 le name, and.**
271e0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 the origin_ rout
271f0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
27200 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 column name..**
27210 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
27220 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ing is valid unt
27230 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 il the [prepared
27240 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 statement] is d
27250 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e estroyed.** usin
27260 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
27270 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
27280 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
27290 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 tion is requeste
272a0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 d.** again in a
272b0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 different encodi
272c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 ng..**.** The na
272d0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 mes returned are
272e0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e the original un
272f0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f -aliased names o
27300 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 f the.** databas
27310 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f e, table, and co
27320 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lumn..**.** The
27330 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
27340 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 o the following
27350 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 calls is a [prep
27360 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
27370 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
27380 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
27390 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
273a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
273b0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 rned by.** the s
273c0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 tatement, where
273d0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
273e0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
273f0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 t..**.** If the
27400 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
27410 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 ned by the state
27420 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 ment is an expre
27430 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 ssion or.** subq
27440 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 uery and is not
27450 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 a column value,
27460 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 then all of thes
27470 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
27480 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 rn.** NULL. The
27490 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 se routine might
274a0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c also return NUL
274b0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c L if a memory al
274c0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a location error.*
274d0 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 * occurs. Other
274e0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
274f0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
27500 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
27510 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e ase, table.** an
27520 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 d column that qu
27530 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
27540 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
27550 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 from..**.** As w
27560 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 ith all other SQ
27570 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 Lite APIs, those
27580 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 postfixed with
27590 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 "16" return.** U
275a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 TF-16 encoded st
275b0 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 rings, the other
275c0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
275d0 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a n UTF-8. {END}.*
275e0 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 *.** These APIs
275f0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
27600 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
27610 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
27620 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
27630 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
27640 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
27650 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
27660 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
27670 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 {A13751}.** If t
27680 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
27690 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
276a0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ore of these rou
276b0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 tines against th
276c0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 e same.** prepar
276d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ed statement and
276e0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 column at the s
276f0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
27700 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a e results are.**
27710 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
27720 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
27730 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65 .** {H13741} The
27740 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
27750 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 _database_name(S
27760 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
27770 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a eturns either.**
27780 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 the UT
27790 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 F-8 zero-termina
277a0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 ted name of the
277b0 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 database from wh
277c0 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ich the.**
277d0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 Nth result c
277e0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 olumn of the [pr
277f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27800 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 ] S is extracted
27810 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
27820 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 NULL if the Nth
27830 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 column of S is
27840 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 a general expres
27850 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 sion.**
27860 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f or if unable to
27870 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
27880 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 to store the na
27890 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 me..**.** {H1374
278a0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
278b0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
278c0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 name16(S,N)] int
278d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
278e0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
278f0 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 the UTF-16 nat
27900 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a ive byte order z
27910 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e ero-terminated n
27920 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
27930 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ase.**
27940 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e from which the N
27950 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e th result column
27960 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 of the [prepare
27970 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
27980 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 s.** ex
27990 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c tracted, or NULL
279a0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 if the Nth colu
279b0 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e mn of S is a gen
279c0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a eral expression.
279d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 ** or i
279e0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f f unable to allo
279f0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 cate memory to s
27a00 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a tore the name..*
27a10 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 *.** {H13743} Th
27a20 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
27a30 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e n_table_name(S,N
27a40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
27a50 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 urns either.**
27a60 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d the UTF-
27a70 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
27a80 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 d name of the ta
27a90 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 ble from which t
27aa0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
27ab0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e th result column
27ac0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 of the [prepare
27ad0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
27ae0 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 s extracted,.**
27af0 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c or NULL
27b00 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 if the Nth colu
27b10 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e mn of S is a gen
27b20 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a eral expression.
27b30 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 ** or i
27b40 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f f unable to allo
27b50 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 cate memory to s
27b60 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a tore the name..*
27b70 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 *.** {H13744} Th
27b80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
27b90 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 n_table_name16(S
27ba0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
27bb0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a eturns either.**
27bc0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 the UT
27bd0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
27be0 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d order zero-term
27bf0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 inated name of t
27c00 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 he table.**
27c10 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 from which
27c20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 the Nth result c
27c30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 olumn of the [pr
27c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27c50 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 ] S is.**
27c60 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 extracted, or
27c70 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 NULL if the Nth
27c80 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 column of S is
27c90 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 a general expres
27ca0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 sion.**
27cb0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f or if unable to
27cc0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
27cd0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 to store the na
27ce0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 me..**.** {H1374
27cf0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 5} The [sqlite3_
27d00 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
27d10 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 me(S,N)] interfa
27d20 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 ce returns eithe
27d30 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
27d40 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 e UTF-8 zero-ter
27d50 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 minated name of
27d60 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e the table column
27d70 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a from which the.
27d80 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
27d90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
27da0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
27db0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 tatement] S is e
27dc0 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 xtracted,.**
27dd0 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 or NULL if
27de0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
27df0 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 of S is a genera
27e00 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 l expression.**
27e10 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 or if u
27e20 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
27e30 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 e memory to stor
27e40 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a e the name..**.*
27e50 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b * {H13746} The [
27e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
27e70 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e rigin_name16(S,N
27e80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
27e90 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 urns either.**
27ea0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d the UTF-
27eb0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
27ec0 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e rder zero-termin
27ed0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 ated name of the
27ee0 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 table.**
27ef0 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 column from w
27f00 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 hich the Nth res
27f10 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ult column of th
27f20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
27f30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27f40 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 t] S is extracte
27f50 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 d, or NULL if th
27f60 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 e Nth column.**
27f70 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73 of S is
27f80 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 a general expre
27f90 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 ssion or if unab
27fa0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
27fb0 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 emory.**
27fc0 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e to store the n
27fd0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ame..**.** {H137
27fe0 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 48} The return v
27ff0 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 alues from.**
28000 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
28010 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
28020 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 name | column me
28030 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 tadata interface
28040 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 s].** a
28050 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65 re valid for the
28060 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 lifetime of the
28070 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
28080 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ment].**
28090 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 or until the e
280a0 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 ncoding is chang
280b0 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 ed by another me
280c0 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 tadata.**
280d0 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c interface cal
280e0 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 l for the same p
280f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
28100 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a t and column..**
28110 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a .** ASSUMPTIONS:
28120 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 .**.** {A13751}
28130 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
28140 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
28150 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 or more.**
28160 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c [sqlite3_col
28170 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
28180 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 e | column metad
28190 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a ata interfaces].
281a0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 ** for
281b0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 the same [prepar
281c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
281d0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a d result column.
281e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74 ** at t
281f0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
28200 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
28210 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a e undefined..*/.
28220 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
28230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
28240 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ase_name(sqlite3
28250 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
28260 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
28270 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
28280 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
28290 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
282a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
282b0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
282c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
282d0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 int);.const void
282e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
282f0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 _table_name16(sq
28300 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
28310 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
28320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
28330 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 gin_name(sqlite3
28340 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
28350 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
28360 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
28370 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
28380 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
28390 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
283a0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 red Datatype Of
283b0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b A Query Result {
283c0 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e H13760} <S10700>
283d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
283e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
283f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
28400 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ent]..** If this
28410 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
28420 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
28430 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 nt and the Nth c
28440 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 olumn of the.**
28450 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 returned result
28460 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c set of that [SEL
28470 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 ECT] is a table
28480 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a column (not an.*
28490 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
284a0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 subquery) then t
284b0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
284c0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a of the table.**
284d0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 column is retur
284e0 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 ned. If the Nth
284f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
28500 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a esult set is an.
28510 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
28520 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 subquery, then
28530 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
28540 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 s returned..** T
28550 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
28560 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 ng is always UTF
28570 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 -8 encoded. {END
28580 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d }.**.** For exam
28590 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 ple, given the d
285a0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a atabase schema:.
285b0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 **.** CREATE TAB
285c0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 LE t1(c1 VARIANT
285d0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 );.**.** and the
285e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 following state
285f0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
28600 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 led:.**.** SELEC
28610 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f T c1 + 1, c1 FRO
28620 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 M t1;.**.** this
28630 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 routine would r
28640 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 eturn the string
28650 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 "VARIANT" for t
28660 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 he second result
28670 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 .** column (i==1
28680 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f ), and a NULL po
28690 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 inter for the fi
286a0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d rst result colum
286b0 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 n (i==0)..**.**
286c0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
286d0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 mic run-time typ
286e0 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 ing. So just be
286f0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a cause a column.*
28700 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f * is declared to
28710 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 contain a parti
28720 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 cular type does
28730 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 not mean that th
28740 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 e.** data stored
28750 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 in that column
28760 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 is of the declar
28770 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 ed type. SQLite
28780 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 is.** strongly
28790 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 typed, but the t
287a0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 yping is dynamic
287b0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 not static. Ty
287c0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 pe.** is associa
287d0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 ted with individ
287e0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 ual values, not
287f0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e with the contain
28800 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 ers.** used to h
28810 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 old those values
28820 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
28830 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 TS:.**.** {H1376
28840 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 1} A successful
28850 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
28860 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
28870 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 e(S,N)] returns
28880 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a a.** z
28890 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
288a0 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 TF-8 string cont
288b0 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 aining the decla
288c0 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 red datatype.**
288d0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
288e0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
288f0 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68 at appears as th
28900 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 e Nth column (nu
28910 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 mbered.**
28920 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 from 0) of t
28930 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f he result set to
28940 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
28950 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a tatement] S..**.
28960 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73 ** {H13762} A s
28970 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
28980 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d o [sqlite3_colum
28990 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e n_decltype16(S,N
289a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 )].**
289b0 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 returns a zero-t
289c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 erminated UTF-16
289d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
289e0 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 er string.**
289f0 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e containin
28a00 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 g the declared d
28a10 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 atatype of the t
28a20 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
28a30 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 appears.**
28a40 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 as the Nth
28a50 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 column (numbere
28a60 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 d from 0) of the
28a70 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 result set to t
28a80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 he.**
28a90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
28aa0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ent] S..**.** {H
28ab0 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 13763} If N is
28ac0 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e less than 0 or N
28ad0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e is greater than
28ae0 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 or equal to.**
28af0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 the nu
28b00 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
28b10 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
28b20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a statement] S,.*
28b30 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 * or i
28b40 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
28b50 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 of S is an expr
28b60 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
28b70 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 ry rather.**
28b80 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 than a ta
28b90 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 ble column, or i
28ba0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
28bb0 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a ation failure.**
28bc0 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 occur
28bd0 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e s during encodin
28be0 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 g conversions, t
28bf0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
28c00 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
28c10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
28c20 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 pe(S,N)] or.**
28c30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
28c40 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
28c50 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e e16(S,N)] return
28c60 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 NULL..*/.const
28c70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
28c80 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 lumn_decltype(sq
28c90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
28ca0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
28cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
28cc0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f ltype16(sqlite3_
28cd0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
28ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 ** CAPI3REF: Eva
28cf0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
28d00 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 tement {H13200}
28d10 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 <S10000>.**.** A
28d20 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 fter a [prepared
28d30 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 statement] has
28d40 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 been prepared us
28d50 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 ing either.** [s
28d60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
28d70 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
28d80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
28d90 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c or one of the l
28da0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
28db0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
28dc0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 pare()] or [sqli
28dd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
28de0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a , this function.
28df0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ** must be calle
28e00 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
28e10 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 mes to evaluate
28e20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a the statement..*
28e30 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 *.** The details
28e40 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 of the behavior
28e50 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
28e60 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 step() interface
28e70 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 depend.** on wh
28e80 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d ether the statem
28e90 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 ent was prepared
28ea0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 using the newer
28eb0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a "v2" interface.
28ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
28ed0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
28ee0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
28ef0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c _v2()] or the ol
28f00 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e der legacy.** in
28f10 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 terface [sqlite3
28f20 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
28f30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28f40 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 16()]. The use
28f50 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 of the.** new "v
28f60 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
28f70 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
28f80 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
28f90 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a but the legacy.
28fa0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c ** interface wil
28fb0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 l continue to be
28fc0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a supported..**.*
28fd0 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 * In the legacy
28fe0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
28ff0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
29000 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
29010 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
29020 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
29030 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
29040 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
29050 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
29060 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 With the "v2" i
29070 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
29080 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 the other [resu
29090 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 lt codes] or.**
290a0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
290b0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 codes] might be
290c0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c returned as wel
290d0 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 l..**.** [SQLITE
290e0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 _BUSY] means tha
290f0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 t the database e
29100 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 ngine was unable
29110 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a to acquire the.
29120 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b ** database lock
29130 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f s it needs to do
29140 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 its job. If th
29150 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
29160 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 [COMMIT].** or
29170 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f occurs outside o
29180 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 f an explicit tr
29190 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
291a0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 you can retry th
291b0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 e.** statement.
291c0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
291d0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d t is not a [COMM
291e0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 IT] and occurs w
291f0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 ithin a.** expli
29200 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 cit transaction
29210 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 then you should
29220 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 rollback the tra
29230 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a nsaction before.
29240 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a ** continuing..*
29250 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e *.** [SQLITE_DON
29260 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
29270 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
29280 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
29290 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
292a0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
292b0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
292c0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
292d0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
292e0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
292f0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
29300 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
29310 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
29320 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
29330 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
29340 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
29350 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
29360 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
29370 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
29380 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 ny data, then [S
29390 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 QLITE_ROW].** is
293a0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 returned each t
293b0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 ime a new row of
293c0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 data is ready f
293d0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 or processing by
293e0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 the.** caller.
293f0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 The values may b
29400 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 e accessed using
29410 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 the [column acc
29420 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a ess functions]..
29430 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
29440 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 ) is called agai
29450 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 n to retrieve th
29460 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 e next row of da
29470 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ta..**.** [SQLIT
29480 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
29490 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
294a0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
294b0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
294c0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
294d0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
294e0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
294f0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
29500 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
29510 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
29520 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
29530 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
29540 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
29550 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 With the legacy
29560 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 interface, a mor
29570 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
29580 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 code (for examp
29590 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 le,.** [SQLITE_I
295a0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 NTERRUPT], [SQLI
295b0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c TE_SCHEMA], [SQL
295c0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e ITE_CORRUPT], an
295d0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 d so forth).** c
295e0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 an be obtained b
295f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
29600 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 e3_reset()] on t
29610 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
29620 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 statement]. In
29630 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
29640 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
29650 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
29660 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
29670 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
29680 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
29690 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
296a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
296b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
296c0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
296d0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
296e0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
296f0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
29700 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
29710 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
29720 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
29730 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
29740 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
29750 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
29760 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
29770 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
29780 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
29790 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
297a0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
297b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
297c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
297d0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
297e0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
297f0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
29800 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
29810 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 ..**.** <b>Goofy
29820 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 Interface Alert
29830 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 :</b> In the leg
29840 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
29850 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 he sqlite3_step(
29860 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 ).** API always
29870 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 returns a generi
29880 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 c error code, [S
29890 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f QLITE_ERROR], fo
298a0 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 llowing any.** e
298b0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 rror other than
298c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e [SQLITE_BUSY] an
298d0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 d [SQLITE_MISUSE
298e0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c ]. You must cal
298f0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 l.** [sqlite3_re
29900 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
29910 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
29920 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 n order to find
29930 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 one of the.** sp
29940 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f ecific [error co
29950 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 des] that better
29960 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
29970 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 rror..** We admi
29980 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 t that this is a
29990 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 goofy design.
299a0 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 The problem has
299b0 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 been fixed.** wi
299c0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
299d0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 rface. If you p
299e0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f repare all of yo
299f0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ur SQL statement
29a00 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 s.** using eithe
29a10 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
29a20 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
29a30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
29a40 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 2()] instead.**
29a50 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 of the legacy [s
29a60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
29a70 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
29a80 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 repare16()] inte
29a90 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 rfaces,.** then
29aa0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
29ab0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 c [error codes]
29ac0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 are returned dir
29ad0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 ectly.** by sqli
29ae0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 te3_step(). The
29af0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 use of the "v2"
29b00 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
29b10 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a commended..**.**
29b20 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
29b30 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20 ** {H13202} If
29b40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
29b50 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 atement] S is re
29b60 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 ady to be run, t
29b70 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
29b80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
29b90 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 )] advances that
29ba0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
29bb0 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 ent until.**
29bc0 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f completio
29bd0 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 n or until it is
29be0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e ready to return
29bf0 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 another row of
29c00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
29c10 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 result set, or
29c20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 until an [sqlite
29c30 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 3_interrupt | in
29c40 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 terrupt].**
29c50 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 or a run-t
29c60 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ime error occurs
29c70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d ..**.** {H15304}
29c80 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f When a call to
29c90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
29ca0 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70 )] causes the [p
29cb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29cc0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 t].**
29cd0 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 S to run to comp
29ce0 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 letion, the func
29cf0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 tion returns [SQ
29d00 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a LITE_DONE]..**.*
29d10 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e * {H15306} When
29d20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
29d30 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f te3_step(S)] sto
29d40 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ps because it is
29d50 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 ready to.**
29d60 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e return an
29d70 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 other row of the
29d80 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20 result set, it
29d90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
29da0 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 ROW]..**.** {H15
29db0 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 308} If a call
29dc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
29dd0 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 (S)] encounters
29de0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 an.**
29df0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
29e00 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 pt | interrupt]
29e10 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 or a run-time er
29e20 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ror,.**
29e30 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 it returns an
29e40 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f appropriate erro
29e50 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e r code that is n
29e60 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 ot one of.**
29e70 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f [SQLITE_O
29e80 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d K], [SQLITE_ROW]
29e90 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e , or [SQLITE_DON
29ea0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 E]..**.** {H1531
29eb0 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 0} If an [sqlit
29ec0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 e3_interrupt | i
29ed0 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 nterrupt] or a r
29ee0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a un-time error.**
29ef0 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 occur
29f00 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 s during a call
29f10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
29f20 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 (S)].**
29f30 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 for a [prepare
29f40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 d statement] S c
29f50 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 reated using.**
29f60 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 legacy
29f70 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
29f80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
29f90 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 or.**
29fa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
29fb0 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 16()], then the
29fc0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
29fd0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 either.**
29fe0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 [SQLITE_ERR
29ff0 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 OR], [SQLITE_BUS
2a000 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d Y], or [SQLITE_M
2a010 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 ISUSE]..*/.int s
2a020 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
2a030 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
2a040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
2a050 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
2a060 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b n a result set {
2a070 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e H13770} <S10700>
2a080 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 .**.** Returns t
2a090 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c he number of val
2a0a0 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 ues in the curre
2a0b0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2a0c0 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 sult set..**.**
2a0d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2a0e0 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65 * {H13771} Afte
2a0f0 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c r a call to [sql
2a100 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 ite3_step(S)] th
2a110 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 at returns [SQLI
2a120 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 TE_ROW],.**
2a130 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 the [sqlit
2a140 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 e3_data_count(S)
2a150 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 ] routine will r
2a160 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 eturn the same v
2a170 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 alue.**
2a180 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 as the [sqlite
2a190 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 3_column_count(S
2a1a0 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a )] function..**.
2a1b0 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74 ** {H13772} Aft
2a1c0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 er [sqlite3_step
2a1d0 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 (S)] has returne
2a1e0 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 d any value othe
2a1f0 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 r than.**
2a200 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d [SQLITE_ROW]
2a210 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 or before [sqli
2a220 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
2a230 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 been called on
2a240 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2a250 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2a260 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 ment] for the fi
2a270 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 rst time since i
2a280 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 t was.**
2a290 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 [sqlite3_prep
2a2a0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 are | prepared]
2a2b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
2a2c0 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 t | reset],.**
2a2d0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 the [sq
2a2e0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2a2f0 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 (S)] routine ret
2a300 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e urns zero..*/.in
2a310 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 t sqlite3_data_c
2a320 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2a330 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2a340 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 * CAPI3REF: Fund
2a350 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 amental Datatype
2a360 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 s {H10265} <S101
2a370 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 10><S10120>.** K
2a380 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f EYWORDS: SQLITE_
2a390 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 TEXT.**.** {H102
2a3a0 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 66} Every value
2a3b0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e in SQLite has on
2a3c0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d e of five fundam
2a3d0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a ental datatypes:
2a3e0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2a3f0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 li> 64-bit signe
2a400 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 d integer.** <li
2a410 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c > 64-bit IEEE fl
2a420 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
2a430 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 ber.** <li> stri
2a440 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a ng.** <li> BLOB.
2a450 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 ** <li> NULL.**
2a460 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a </ul> {END}.**.*
2a470 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
2a480 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 s are codes for
2a490 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 each of those ty
2a4a0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 pes..**.** Note
2a4b0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f that the SQLITE_
2a4c0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 TEXT constant wa
2a4d0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 s also used in S
2a4e0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a QLite version 2.
2a4f0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 ** for a complet
2a500 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 ely different me
2a510 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 aning. Software
2a520 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 that links agai
2a530 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 nst both.** SQLi
2a540 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 te version 2 and
2a550 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2a560 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 3 should use SQL
2a570 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a ITE3_TEXT, not.*
2a580 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a * SQLITE_TEXT..*
2a590 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2a5a0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 _INTEGER 1.#def
2a5b0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ine SQLITE_FLOAT
2a5c0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
2a5d0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a LITE_BLOB 4.
2a5e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
2a5f0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 ULL 5.#ifdef
2a600 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 SQLITE_TEXT.# u
2a610 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 ndef SQLITE_TEXT
2a620 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 .#else.# define
2a630 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 SQLITE_TEXT
2a640 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 3.#endif.#define
2a650 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 SQLITE3_TEXT
2a660 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 3../*.** CAPI3
2a670 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 REF: Result Valu
2a680 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 es From A Query
2a690 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 {H13800} <S10700
2a6a0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
2a6b0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
2a6c0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 nctions}.**.** T
2a6d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hese routines fo
2a6e0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 rm the "result s
2a6f0 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 et query" interf
2a700 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ace..**.** These
2a710 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2a720 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
2a730 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 ut a single colu
2a740 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e mn of the curren
2a750 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 t.** result row
2a760 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 of a query. In
2a770 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 every case the f
2a780 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
2a790 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
2a7a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2a7b0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
2a7c0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 s being evaluate
2a7d0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
2a7e0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 stmt*].** that w
2a7f0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
2a800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2a810 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f e_v2()] or one o
2a820 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a f its variants).
2a830 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ** and the secon
2a840 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2a850 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
2a860 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 olumn for which
2a870 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 information.** s
2a880 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
2a890 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 d. The leftmost
2a8a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
2a8b0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 esult set has th
2a8c0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a e index 0..**.**
2a8d0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 If the SQL stat
2a8e0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
2a8f0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 urrently point t
2a900 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f o a valid row, o
2a910 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r if the.** colu
2a920 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 mn index is out
2a930 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 of range, the re
2a940 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
2a950 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 d..** These rout
2a960 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ines may only be
2a970 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 called when the
2a980 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
2a990 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
2a9a0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
2a9b0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f urned [SQLITE_RO
2a9c0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a W] and neither.*
2a9d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
2a9e0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 ()] nor [sqlite3
2a9f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 _finalize()] hav
2aa00 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 e been called su
2aa10 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 bsequently..** I
2aa20 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 f any of these r
2aa30 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
2aa40 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 ed after [sqlite
2aa50 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
2aa60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2aa70 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b ze()] or after [
2aa80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2aa90 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 has returned.**
2aaa0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 something other
2aab0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
2aac0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 ], the results a
2aad0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
2aae0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 If [sqlite3_ste
2aaf0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
2ab00 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
2ab10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2ab20 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 ].** are called
2ab30 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 from a different
2ab40 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e thread while an
2ab50 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
2ab60 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 nes.** are pendi
2ab70 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 ng, then the res
2ab80 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
2ab90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
2aba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2abb0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
2abc0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 rns the.** [SQLI
2abd0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
2abe0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 atype code] for
2abf0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 the initial data
2ac00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 type.** of the
2ac10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 result column.
2ac20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c The returned val
2ac30 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 ue is one of [SQ
2ac40 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a LITE_INTEGER],.*
2ac50 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d * [SQLITE_FLOAT]
2ac60 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c , [SQLITE_TEXT],
2ac70 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 [SQLITE_BLOB],
2ac80 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d or [SQLITE_NULL]
2ac90 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 . The value.**
2aca0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2acb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2acc0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e ) is only meanin
2acd0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a gful if no type.
2ace0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 ** conversions h
2acf0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 ave occurred as
2ad00 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e described below.
2ad10 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 After a type c
2ad20 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 onversion,.** th
2ad30 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
2ad40 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
2ad50 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 mn_type() is und
2ad60 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a efined. Future.
2ad70 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ** versions of S
2ad80 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 QLite may change
2ad90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
2ada0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2adb0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 type().** follow
2adc0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ing a type conve
2add0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 rsion..**.** If
2ade0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2adf0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 BLOB or UTF-8 st
2ae00 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
2ae10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2ae20 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 es().** routine
2ae30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2ae40 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2ae50 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
2ae60 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 ng..** If the re
2ae70 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 sult is a UTF-16
2ae80 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
2ae90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2aea0 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a es() converts.**
2aeb0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
2aec0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 TF-8 and then re
2aed0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2aee0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 of bytes..** If
2aef0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2af00 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
2af10 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
2af20 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a mn_bytes() uses.
2af30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
2af40 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
2af50 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
2af60 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 a UTF-8 string
2af70 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
2af80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2af90 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
2afa0 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 g..** The value
2afb0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
2afc0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 t include the ze
2afd0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 ro terminator at
2afe0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 the end.** of t
2aff0 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 he string. For
2b000 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c clarity: the val
2b010 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 ue returned is t
2b020 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
2b030 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 bytes in the str
2b040 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d ing, not the num
2b050 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
2b060 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 s..**.** Strings
2b070 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2b080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2b090 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
2b0a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
2b0b0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
2b0c0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
2b0d0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 s zero terminate
2b0e0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a d. The return.*
2b0f0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c * value from sql
2b100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
2b110 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 () for a zero-le
2b120 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 ngth BLOB is an
2b130 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 arbitrary.** poi
2b140 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 nter, possibly e
2b150 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ven a NULL point
2b160 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
2b170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2b180 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 es16() routine i
2b190 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c s similar to sql
2b1a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2b1b0 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 s().** but leave
2b1c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 s the result in
2b1d0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
2b1e0 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 byte order inst
2b1f0 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a ead of UTF-8..**
2b200 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e The zero termin
2b210 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c ator is not incl
2b220 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 uded in this cou
2b230 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 nt..**.** The ob
2b240 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
2b250 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2b260 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a _value()] is an.
2b270 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 ** [unprotected
2b280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
2b290 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f bject. An unpro
2b2a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2b2b0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d alue object.** m
2b2c0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
2b2d0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 with [sqlite3_bi
2b2e0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 nd_value()] and
2b2f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
2b300 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 value()]..** If
2b310 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 the [unprotected
2b320 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2b330 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
2b340 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
2b350 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
2b360 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 s used in any ot
2b370 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 her way, includi
2b380 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 ng calls.** to r
2b390 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
2b3a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
2b3b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
2b3c0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
2b3d0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
2b3e0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 _bytes()], then
2b3f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
2b400 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2b410 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2b420 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 attempt to conve
2b430 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 rt the value whe
2b440 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 re appropriate.
2b450 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
2b460 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
2b470 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
2b480 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
2b490 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
2b4a0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
2b4b0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
2b4c0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
2b4d0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
2b4e0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
2b4f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
2b500 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 The following t
2b510 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 able details the
2b520 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 conversions.**
2b530 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 that are applied
2b540 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
2b550 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
2b560 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
2b570 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c r><th> Internal<
2b580 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 br>Type <th> Req
2b590 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c uested<br>Type <
2b5a0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a th> Conversion.
2b5b0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 **.** <tr><td>
2b5c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 NULL <td> INT
2b5d0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 EGER <td> Resu
2b5e0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c lt is 0.** <tr><
2b5f0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
2b600 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2b610 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a Result is 0.0.*
2b620 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2b630 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
2b640 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2b650 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
2b660 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2b670 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
2b680 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2b690 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
2b6a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2b6b0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
2b6c0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2b6d0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
2b6e0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2b6f0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
2b700 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
2b710 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
2b720 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
2b730 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
2b740 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
2b750 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
2b760 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
2b770 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2b780 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2b790 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
2b7a0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 om float to inte
2b7b0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
2b7c0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
2b7d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
2b7e0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
2b7f0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
2b800 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
2b810 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
2b820 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 d> Same as FLOAT
2b830 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
2b840 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2b850 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2b860 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 Use atoi().** <t
2b870 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2b880 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2b890 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a td> Use atof().*
2b8a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2b8b0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
2b8c0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
2b8d0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
2b8e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
2b8f0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 GER <td> Conve
2b900 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
2b910 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 use atoi().** <t
2b920 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
2b930 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2b940 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
2b950 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
2b960 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 f().** <tr><td>
2b970 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
2b980 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
2b990 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
2b9a0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
2b9b0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
2b9c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
2b9d0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 The table above
2b9e0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 makes reference
2b9f0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 to standard C li
2ba00 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 brary functions
2ba10 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 atoi().** and at
2ba20 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f of(). SQLite do
2ba30 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 es not really us
2ba40 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e e these function
2ba50 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a s. It has its.*
2ba60 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 * own equivalent
2ba70 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e internal routin
2ba80 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 es. The atoi()
2ba90 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 and atof() names
2baa0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 are.** used in
2bab0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 the table for br
2bac0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 evity and becaus
2bad0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c e they are famil
2bae0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 iar to most.** C
2baf0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a programmers..**
2bb00 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 .** Note that wh
2bb10 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 en type conversi
2bb20 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 ons occur, point
2bb30 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ers returned by
2bb40 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 prior.** calls t
2bb50 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2bb60 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
2bb70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 _column_text(),
2bb80 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 and/or.** sqlite
2bb90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2bba0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 ) may be invalid
2bbb0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f ated..** Type co
2bbc0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f nversions and po
2bbd0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 inter invalidati
2bbe0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a ons might occur.
2bbf0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 ** in the follow
2bc00 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a ing cases:.**.**
2bc10 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
2bc20 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
2bc30 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 t is a BLOB and
2bc40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2bc50 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 ext() or.**
2bc60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2bc70 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
2bc80 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
2bc90 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
2bca0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
2bcb0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
2bcc0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 ing.</li>.** <li
2bcd0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
2bce0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
2bcf0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
2bd00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2bd10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
2bd20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2bd30 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
2bd40 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
2bd50 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
2bd60 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e to UTF-16.
2bd70 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
2bd80 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
2bd90 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 t is UTF-16 text
2bda0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2bdb0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
2bdc0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
2bdd0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 olumn_text() is
2bde0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
2bdf0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
2be00 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
2be10 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a o UTF-8.</li>.**
2be20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e </ul>.**.** Con
2be30 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e versions between
2be40 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 UTF-16be and UT
2be50 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 F-16le are alway
2be60 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 s done in place
2be70 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e and do.** not in
2be80 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 validate a prior
2be90 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 pointer, though
2bea0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 of course the c
2beb0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 ontent of the bu
2bec0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 ffer.** that the
2bed0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 prior pointer p
2bee0 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 oints to will ha
2bef0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
2bf00 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
2bf10 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
2bf20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
2bf30 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
2bf40 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
2bf50 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
2bf60 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
2bf70 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
2bf80 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
2bf90 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
2bfa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
2bfb0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f t and easiest to
2bfc0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 remember policy
2bfd0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 is to invoke th
2bfe0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
2bff0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f in one of the fo
2c000 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a llowing ways:.**
2c010 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 .** <ul>.** <li
2c020 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2c030 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
2c040 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2c050 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
2c060 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
2c070 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
2c080 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
2c090 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
2c0a0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
2c0b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2c0c0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
2c0d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c0e0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
2c0f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
2c100 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f other words, yo
2c110 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 u should call sq
2c120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2c130 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t(),.** sqlite3_
2c140 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f column_blob(), o
2c150 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2c160 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 _text16() first
2c170 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 to force the res
2c180 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ult.** into the
2c190 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 desired format,
2c1a0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 then invoke sqli
2c1b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2c1c0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
2c1d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2c1e0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 ) to find the si
2c1f0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ze of the result
2c200 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 . Do not mix ca
2c210 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 lls.** to sqlite
2c220 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
2c230 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
2c240 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
2c250 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
2c260 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2c270 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d (), and do not m
2c280 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ix calls to sqli
2c290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2c2a0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 6().** with call
2c2b0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
2c2c0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a umn_bytes()..**.
2c2d0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 ** The pointers
2c2e0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
2c2f0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
2c300 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
2c310 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
2c320 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
2c330 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
2c340 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
2c350 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2c360 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2c370 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 )] is called. T
2c380 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 he memory space
2c390 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 used to hold str
2c3a0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 ings.** and BLOB
2c3b0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d s is freed autom
2c3c0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 atically. Do <b
2c3d0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 >not</b> pass th
2c3e0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
2c3f0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ned.** [sqlite3_
2c400 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 column_blob()],
2c410 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2c420 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e text()], etc. in
2c430 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
2c440 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ree()]..**.** If
2c450 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
2c460 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
2c470 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 s during the eva
2c480 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a luation of any.*
2c490 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 * of these routi
2c4a0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 nes, a default v
2c4b0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
2c4c0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 . The default v
2c4d0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 alue.** is eithe
2c4e0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c r the integer 0,
2c4f0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f the floating po
2c500 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 int number 0.0,
2c510 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 or a NULL.** poi
2c520 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e nter. Subsequen
2c530 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
2c540 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 te3_errcode()] w
2c550 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 ill return.** [S
2c560 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
2c570 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
2c580 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 **.** {H13803} T
2c590 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
2c5a0 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e mn_blob(S,N)] in
2c5b0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
2c5c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2c5d0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
2c5e0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
2c5f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
2c600 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
2c610 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2c620 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f tatement] S into
2c630 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e a BLOB and then
2c640 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 returns a.**
2c650 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 pointer t
2c660 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 o the converted
2c670 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 value..**.** {H1
2c680 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 3806} The [sqlit
2c690 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2c6a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2c6b0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 returns the.**
2c6c0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f number o
2c6d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 f bytes in the B
2c6e0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 LOB or string (e
2c6f0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a xclusive of the.
2c700 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f ** zero
2c710 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 terminator on t
2c720 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 he string) that
2c730 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 was returned by
2c740 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2c750 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
2c760 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c to [sqlite3_col
2c770 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f umn_blob(S,N)] o
2c780 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
2c790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2c7a0 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 xt(S,N)]..**.**
2c7b0 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 {H13809} The [sq
2c7c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2c7d0 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 es16(S,N)] inter
2c7e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
2c7f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d .** num
2c800 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2c810 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c the string (excl
2c820 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 usive of the.**
2c830 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 zero te
2c840 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 rminator on the
2c850 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 string) that was
2c860 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
2c870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 .** mos
2c880 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2c890 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c8a0 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a _text16(S,N)]..*
2c8b0 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 *.** {H13812} Th
2c8c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
2c8d0 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 n_double(S,N)] i
2c8e0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
2c8f0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2c900 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 Nth column in
2c910 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 the current row
2c920 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2c930 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 t for the.**
2c940 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
2c950 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 statement] S int
2c960 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 o a floating poi
2c970 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 nt value and.**
2c980 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
2c990 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 a copy of that
2c9a0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 value..**.** {H1
2c9b0 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 3815} The [sqlit
2c9c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c e3_column_int(S,
2c9d0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f N)] interface co
2c9e0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 nverts the.**
2c9f0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d Nth colum
2ca00 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 n in the current
2ca10 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
2ca20 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a lt set for the.*
2ca30 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
2ca40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2ca50 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 S into a 64-bit
2ca60 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 signed integer a
2ca70 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 nd.** r
2ca80 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 eturns the lower
2ca90 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 32 bits of that
2caa0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
2cab0 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 {H13818} The [sq
2cac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
2cad0 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 64(S,N)] interfa
2cae0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
2caf0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
2cb00 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 column in the cu
2cb10 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
2cb20 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 result set for
2cb30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2cb40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2cb50 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 ent] S into a 64
2cb60 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
2cb70 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ger and.**
2cb80 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f returns a co
2cb90 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 py of that integ
2cba0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 er..**.** {H1382
2cbb0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
2cbc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 column_text(S,N)
2cbd0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
2cbe0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
2cbf0 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 Nth column
2cc00 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
2cc10 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
2cc20 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 set for.**
2cc30 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 the [prepar
2cc40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2cc50 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d into a zero-term
2cc60 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 inated UTF-8.**
2cc70 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 string
2cc80 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
2cc90 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 inter to that st
2cca0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ring..**.** {H13
2ccb0 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 824} The [sqlite
2ccc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2ccd0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2cce0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2ccf0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c Nth col
2cd00 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 umn in the curre
2cd10 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2cd20 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 sult set for the
2cd30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2cd40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2cd50 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d ] S into a zero-
2cd60 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 terminated 2-byt
2cd70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c e.** al
2cd80 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 igned UTF-16 nat
2cd90 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 ive byte order s
2cda0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2cdb0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 s.** a
2cdc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
2cdd0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 string..**.** {H
2cde0 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 13827} The [sqli
2cdf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2ce00 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2ce10 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 returns.**
2ce20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 one of [SQLI
2ce30 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_NULL], [SQLIT
2ce40 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c E_INTEGER], [SQL
2ce50 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 ITE_FLOAT],.**
2ce60 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
2ce70 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 TEXT], or [SQLIT
2ce80 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f E_BLOB] as appro
2ce90 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 priate for.**
2cea0 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 the Nth c
2ceb0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
2cec0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
2ced0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a result set for.*
2cee0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
2cef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2cf00 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nt] S..**.** {H1
2cf10 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 3830} The [sqlit
2cf20 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2cf30 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2cf40 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 returns a.**
2cf50 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f pointer to
2cf60 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
2cf70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2cf80 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a object for the.*
2cf90 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 * Nth c
2cfa0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
2cfb0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
2cfc0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a result set for.*
2cfd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
2cfe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2cff0 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 nt] S..*/.const
2d000 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2d010 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 lumn_blob(sqlite
2d020 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2d030 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2d040 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c column_bytes(sql
2d050 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2d060 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
2d070 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2d080 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2d090 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 int iCol);.doub
2d0a0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d le sqlite3_colum
2d0b0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 n_double(sqlite3
2d0c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2d0d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
2d0e0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 olumn_int(sqlite
2d0f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2d100 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 l);.sqlite3_int6
2d110 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 4 sqlite3_column
2d120 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
2d130 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2d140 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 .const unsigned
2d150 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2d160 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 lumn_text(sqlite
2d170 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2d180 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a l);.const void *
2d190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2d1a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
2d1b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2d1c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2d1d0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f mn_type(sqlite3_
2d1e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2d1f0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 ;.sqlite3_value
2d200 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2d210 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
2d220 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2d230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2d240 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
2d250 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
2d260 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 ject {H13300} <S
2d270 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 70300><S30100>.*
2d280 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2d290 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
2d2a0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
2d2b0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
2d2c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2d2d0 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 .** If the state
2d2e0 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 ment was execute
2d2f0 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f d successfully o
2d300 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 r not executed a
2d310 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 t all, then.** S
2d320 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
2d330 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 rned. If executi
2d340 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
2d350 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 ent failed then
2d360 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 an.** [error cod
2d370 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
2d380 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
2d390 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
2d3a0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 his routine can
2d3b0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
2d3c0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 point during th
2d3d0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 e execution of t
2d3e0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
2d3f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 statement]. If
2d400 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 the virtual mach
2d410 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 ine has not.** c
2d420 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 ompleted executi
2d430 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 on when this rou
2d440 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 tine is called,
2d450 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 that is like.**
2d460 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 encountering an
2d470 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c error or an [sql
2d480 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c ite3_interrupt |
2d490 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 interrupt]..**
2d4a0 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 Incomplete updat
2d4b0 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 es may be rolled
2d4c0 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 back and transa
2d4d0 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c ctions canceled,
2d4e0 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e .** depending on
2d4f0 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 the circumstanc
2d500 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b es, and the.** [
2d510 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 error code] retu
2d520 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 rned will be [SQ
2d530 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a LITE_ABORT]..**.
2d540 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
2d550 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 *.** {H11302} Th
2d560 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c e [sqlite3_final
2d570 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 ize(S)] interfac
2d580 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a e destroys the.*
2d590 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
2d5a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d5b0 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 S and releases a
2d5c0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d ll.** m
2d5d0 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 emory and file r
2d5e0 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 esources held by
2d5f0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a that object..**
2d600 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20 .** {H11304} If
2d610 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2d620 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2d630 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
2d640 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
2d650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d660 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e t] S returned an
2d670 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 error,.**
2d680 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
2d690 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 3_finalize(S)] r
2d6a0 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 eturns that same
2d6b0 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 error..*/.int s
2d6c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2d6d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2d6e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
2d6f0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 I3REF: Reset A P
2d700 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2d710 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 t Object {H13330
2d720 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
2d730 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
2d740 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
2d750 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
2d760 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2d770 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
2d780 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e t back to its in
2d790 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 itial state, rea
2d7a0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 dy to be re-exec
2d7b0 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c uted..** Any SQL
2d7c0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 statement varia
2d7d0 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 bles that had va
2d7e0 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 lues bound to th
2d7f0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 em using.** the
2d800 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2d810 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e ob | sqlite3_bin
2d820 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 d_*() API] retai
2d830 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a n their values..
2d840 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f ** Use [sqlite3_
2d850 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 clear_bindings()
2d860 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 ] to reset the b
2d870 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b indings..**.** {
2d880 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c H11332} The [sql
2d890 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
2d8a0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
2d8b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2d8c0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 atement] S.**
2d8d0 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 back to t
2d8e0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
2d8f0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a its program..**.
2d900 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 ** {H11334} If t
2d910 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
2d920 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2d930 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
2d940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2d950 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2d960 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 ] S returned [SQ
2d970 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 LITE_ROW] or [SQ
2d980 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 LITE_DONE],.**
2d990 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 or if [s
2d9a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2d9b0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 has never before
2d9c0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 been called on
2d9d0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 S,.** t
2d9e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
2d9f0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
2da00 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
2da10 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 * {H11336} If th
2da20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2da30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2da40 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
2da50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
2da60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2da70 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 S indicated an
2da80 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 error, then.**
2da90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2daa0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
2dab0 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 ns an appropriat
2dac0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a e [error code]..
2dad0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 **.** {H11338} T
2dae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
2daf0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 t(S)] interface
2db00 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
2db10 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 the values.**
2db20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 of any [s
2db30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2db40 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 |bindings] on th
2db50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2db60 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 ement] S..*/.int
2db70 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 sqlite3_reset(s
2db80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2db90 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2dba0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 3REF: Create Or
2dbb0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e Redefine SQL Fun
2dbc0 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 ctions {H16100}
2dbd0 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S20200>.** KEYW
2dbe0 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 ORDS: {function
2dbf0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 creation routine
2dc00 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
2dc10 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 {application-def
2dc20 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2dc30 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 n}.** KEYWORDS:
2dc40 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 {application-def
2dc50 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2dc60 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
2dc70 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 two functions (c
2dc80 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
2dc90 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
2dca0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2dcb0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
2dcc0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
2dcd0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2dce0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
2dcf0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
2dd00 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
2dd10 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
2dd20 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
2dd30 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 nly difference b
2dd40 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 etween the.** tw
2dd50 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 o is that the se
2dd60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 cond parameter,
2dd70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2dd80 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f (scalar) functio
2dd90 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
2dda0 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e e, is encoded in
2ddb0 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 UTF-8 for sqlit
2ddc0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2ddd0 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a on() and UTF-16.
2dde0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
2ddf0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
2de00 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 ()..**.** The fi
2de10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
2de20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2de30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 onnection] to wh
2de40 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 ich the SQL.** f
2de50 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 unction is to be
2de60 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 added. If a si
2de70 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 ngle program use
2de80 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
2de90 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2dea0 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c ection internall
2deb0 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 y, then SQL func
2dec0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 tions must be ad
2ded0 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 ded individually
2dee0 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 to.** each data
2def0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
2df00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
2df10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
2df20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 he name of the S
2df30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 QL function to b
2df40 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 e created or.**
2df50 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 redefined. The
2df60 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 length of the na
2df70 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f me is limited to
2df80 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 255 bytes, excl
2df90 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 usive of.** the
2dfa0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e zero-terminator.
2dfb0 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
2dfc0 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 name length limi
2dfd0 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e t is in bytes, n
2dfe0 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 ot.** characters
2dff0 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 . Any attempt t
2e000 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 o create a funct
2e010 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 ion with a longe
2e020 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 r name.** will r
2e030 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 esult in [SQLITE
2e040 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 _ERROR] being re
2e050 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
2e060 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2e070 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 r (nArg).** is t
2e080 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
2e090 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 uments that the
2e0a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
2e0b0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b ** aggregate tak
2e0c0 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 es. If this para
2e0d0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 meter is negativ
2e0e0 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 e, then the SQL
2e0f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
2e100 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
2e110 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
2e120 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a arguments..**.**
2e130 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
2e140 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c meter, eTextRep,
2e150 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a specifies what.
2e160 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 ** [SQLITE_UTF8
2e170 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d | text encoding]
2e180 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 this SQL functi
2e190 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a on prefers for.*
2e1a0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 * its parameters
2e1b0 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 . Any SQL funct
2e1c0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
2e1d0 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c on should be abl
2e1e0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 e to work.** wor
2e1f0 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 k with UTF-8, UT
2e200 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 F-16le, or UTF-1
2e210 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6be. But some i
2e220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
2e230 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 ay be.** more ef
2e240 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 ficient with one
2e250 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 encoding than a
2e260 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 nother. It is a
2e270 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 llowed to.** inv
2e280 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 oke sqlite3_crea
2e290 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 te_function() or
2e2a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2e2b0 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c function16() mul
2e2c0 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 tiple.** times w
2e2d0 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e ith the same fun
2e2e0 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 ction but with d
2e2f0 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 ifferent values
2e300 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 of eTextRep..**
2e310 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d When multiple im
2e320 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
2e330 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
2e340 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 on are available
2e350 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c , SQLite.** will
2e360 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 pick the one th
2e370 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 at involves the
2e380 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
2e390 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e data conversion.
2e3a0 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 .** If there is
2e3b0 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d only a single im
2e3c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 plementation whi
2e3d0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 ch does not care
2e3e0 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e what text.** en
2e3f0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 coding is used,
2e400 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
2e410 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
2e420 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e be [SQLITE_ANY].
2e430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 .**.** The fifth
2e440 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
2e450 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 arbitrary point
2e460 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 er. The impleme
2e470 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a ntation of the.*
2e480 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 * function can g
2e490 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 ain access to th
2e4a0 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 is pointer using
2e4b0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
2e4c0 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 ata()]..**.** Th
2e4d0 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 e seventh, eight
2e4e0 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 h and ninth para
2e4f0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 meters, xFunc, x
2e500 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c Step and xFinal,
2e510 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 are.** pointers
2e520 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 to C-language f
2e530 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d unctions that im
2e540 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
2e550 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
2e560 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c ggregate. A scal
2e570 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ar SQL function
2e580 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
2e590 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
2e5a0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 e xFunc.** callb
2e5b0 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 ack only, NULL p
2e5c0 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 ointers should b
2e5d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
2e5e0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
2e5f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
2e600 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c An aggregate SQL
2e610 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
2e620 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
2e630 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a tion of xStep.**
2e640 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 and xFinal and
2e650 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 NULL should be p
2e660 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e assed for xFunc.
2e670 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 To delete an ex
2e680 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 isting.** SQL fu
2e690 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
2e6a0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 ate, pass NULL f
2e6b0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e or all three fun
2e6c0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e ction callbacks.
2e6d0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 .**.** It is per
2e6e0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 mitted to regist
2e6f0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c er multiple impl
2e700 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
2e710 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 he same.** funct
2e720 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 ions with the sa
2e730 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 me name but with
2e740 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e either differin
2e750 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 g numbers of.**
2e760 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 arguments or dif
2e770 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 fering preferred
2e780 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e text encodings.
2e790 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 SQLite will us
2e7a0 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 e.** the impleme
2e7b0 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f ntation most clo
2e7c0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 sely matches the
2e7d0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 way in which th
2e7e0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f e.** SQL functio
2e7f0 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75 n is used. A fu
2e800 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
2e810 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e ation with a non
2e820 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 -negative.** nAr
2e830 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 g parameter is a
2e840 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 better match th
2e850 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d an a function im
2e860 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 plementation wit
2e870 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 h.** a negative
2e880 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f nArg. A functio
2e890 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 n where the pref
2e8a0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
2e8b0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 ing.** matches t
2e8c0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f he database enco
2e8d0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 ding is a better
2e8e0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 .** match than a
2e8f0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
2e900 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 the encoding is
2e910 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 different. .**
2e920 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 A function where
2e930 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
2e940 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 fference is betw
2e950 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 een UTF16le and
2e960 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 UTF16be.** is a
2e970 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 closer match tha
2e980 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
2e990 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
2e9a0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a difference is.**
2e9b0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e between UTF8 an
2e9c0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 d UTF16..**.** B
2e9d0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e uilt-in function
2e9e0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 s may be overloa
2e9f0 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 ded by new appli
2ea00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2ea10 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 unctions..** The
2ea20 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 first applicati
2ea30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2ea40 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e ion with a given
2ea50 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 name overrides
2ea60 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 all.** built-in
2ea70 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 functions in the
2ea80 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
2ea90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 connection] with
2eaa0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a the same name..
2eab0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70 ** Subsequent ap
2eac0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2ead0 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 d functions of t
2eae0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c he same name onl
2eaf0 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 y override .** p
2eb00 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e rior application
2eb10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
2eb20 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 ns that are an e
2eb30 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 xact match for t
2eb40 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
2eb50 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 parameters and p
2eb60 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e referred encodin
2eb70 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c g..**.** An appl
2eb80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2eb90 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
2eba0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
2ebb0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
2ebc0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
2ebd0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
2ebe0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
2ebf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2ec00 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
2ec10 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
2ec20 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
2ec30 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
2ec40 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
2ec50 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
2ec60 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
2ec70 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68 65 20 ** {H16103} The
2ec80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2ec90 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 2e function16(D,X,.
2eca0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 ..)] interface s
2ecb0 68 61 6c 6c 20 62 65 68 61 76 65 0a 2a 2a 20 20 hall behave.**
2ecc0 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 as [sqli
2ecd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2ece0 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e ion(D,X,...)] in
2ecf0 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65 70 every way excep
2ed00 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 t that it.**
2ed10 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74 73 interprets
2ed20 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 the X argument
2ed30 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 as zero-terminat
2ed40 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 ed UTF-16.**
2ed50 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79 74 native byt
2ed60 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 e order instead
2ed70 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 of as zero-termi
2ed80 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a nated UTF-8..**.
2ed90 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75 ** {H16106} A su
2eda0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
2edb0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 ion of the.**
2edc0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2edd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2ede0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e D,X,N,E,...)] in
2edf0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 terface shall re
2ee00 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 gister.**
2ee10 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 or replaces c
2ee20 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
2ee30 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 s in the [databa
2ee40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
2ee50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 .** use
2ee60 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 d to implement t
2ee70 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
2ee80 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 named X with N p
2ee90 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 arameters.**
2eea0 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 and having
2eeb0 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78 a preferred tex
2eec0 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e t encoding of E.
2eed0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20 .**.** {H16109}
2eee0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
2eef0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 l to [sqlite3_cr
2ef00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2ef10 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a X,N,E,P,F,S,L)].
2ef20 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
2ef30 6c 20 72 65 70 6c 61 63 65 20 74 68 65 20 50 2c l replace the P,
2ef40 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c F, S, and L val
2ef50 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 ues from any pri
2ef60 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a or calls with.**
2ef70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 the sa
2ef80 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 me D, X, N, and
2ef90 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 E values..**.**
2efa0 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 {H16112} The [sq
2efb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2efc0 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 ction(D,X,...)]
2efd0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 interface shall
2efe0 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 fail.**
2eff0 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 if the SQL func
2f000 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a tion name X is.*
2f010 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 * longe
2f020 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 r than 255 bytes
2f030 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 exclusive of th
2f040 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
2f050 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 r..**.** {H16118
2f060 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2f070 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
2f080 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d ,X,N,E,P,F,S,L)]
2f090 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 interface.**
2f0a0 20 20 20 20 20 20 20 73 68 61 6c 6c 20 66 61 69 shall fai
2f0b0 6c 20 75 6e 6c 65 73 73 20 65 69 74 68 65 72 20 l unless either
2f0c0 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 53 20 F is NULL and S
2f0d0 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 and L are non-NU
2f0e0 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 20 20 20 20 LL or.***
2f0f0 20 20 46 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 F is non-NULL
2f100 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 and S and L are
2f110 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 NULL..**.** {H16
2f120 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 121} The [sqlite
2f130 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2f140 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 n(D,...)] interf
2f150 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 73 20 ace shall fails
2f160 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 with an.**
2f170 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f error code o
2f180 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 f [SQLITE_BUSY]
2f190 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b if there exist [
2f1a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2f1b0 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 nts].**
2f1c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2f1d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2f1e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a onnection] D..**
2f1f0 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68 65 .** {H16124} The
2f200 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2f210 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c _function(D,X,N,
2f220 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ...)] interface
2f230 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a shall fail with.
2f240 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 65 ** an e
2f250 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 rror code of [SQ
2f260 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 LITE_ERROR] if p
2f270 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 6c 65 arameter N is le
2f280 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ss.** t
2f290 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 han -1 or greate
2f2a0 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a r than 127..**.*
2f2b0 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65 6e 20 * {H16127} When
2f2c0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 N is non-negativ
2f2d0 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f e, the [sqlite3_
2f2e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2f2f0 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 D,X,N,...)].**
2f300 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
2f310 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 e shall register
2f320 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 callbacks to be
2f330 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 invoked for the
2f340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c .** SQL
2f350 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 function.**
2f360 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68 named X wh
2f370 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 en the number of
2f380 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
2f390 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 e SQL function i
2f3a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 s.** ex
2f3b0 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b actly N..**.** {
2f3c0 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 H16130} When N i
2f3d0 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 s -1, the [sqlit
2f3e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2f3f0 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a on(D,X,N,...)].*
2f400 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 * inter
2f410 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 face shall regis
2f420 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f ter callbacks to
2f430 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 be invoked for
2f440 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 the SQL.**
2f450 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d function nam
2f460 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75 ed X with any nu
2f470 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
2f480 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 s..**.** {H16133
2f490 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 } When calls to
2f4a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2f4b0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e function(D,X,N,.
2f4c0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
2f4d0 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c specify multipl
2f4e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f4f0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
2f500 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 nction X.**
2f510 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e and when on
2f520 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f530 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 has N>=0 and th
2f540 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d e other has N=(-
2f550 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 1).** t
2f560 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
2f570 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 n with a non-zer
2f580 6f 20 4e 20 73 68 61 6c 6c 20 62 65 20 70 72 65 o N shall be pre
2f590 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ferred..**.** {H
2f5a0 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 16136} When call
2f5b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 s to [sqlite3_cr
2f5c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2f5d0 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 X,N,E,...)].**
2f5e0 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20 specify
2f5f0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
2f600 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
2f610 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 same function X
2f620 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 with.**
2f630 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 the same number
2f640 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 of arguments N
2f650 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 but with differe
2f660 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 nt.** e
2f670 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e ncodings E, then
2f680 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
2f690 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 ion where E matc
2f6a0 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 hes the.**
2f6b0 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 database enc
2f6c0 6f 64 69 6e 67 20 73 68 61 6c 6c 20 70 72 65 66 oding shall pref
2f6d0 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 erred..**.** {H1
2f6e0 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 6139} For an agg
2f6f0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
2f700 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e ion created usin
2f710 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 g.** [s
2f720 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2f730 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 nction(D,X,N,E,P
2f740 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e ,0,S,L)] the fin
2f750 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 alizer.**
2f760 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 73 68 function L sh
2f770 61 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e all always be in
2f780 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e voked exactly on
2f790 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 ce if the.**
2f7a0 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 step funct
2f7b0 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 ion S is called
2f7c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
2f7d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 s..**.** {H16142
2f7e0 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e } When SQLite in
2f7f0 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 vokes either the
2f800 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 xFunc or xStep
2f810 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 function of.**
2f820 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 an appli
2f830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2f840 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 QL function or a
2f850 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64 ggregate created
2f860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 .** by
2f870 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2f880 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b function()] or [
2f890 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2f8a0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a unction16()],.**
2f8b0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 then t
2f8c0 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c he array of [sql
2f8d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2f8e0 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68 cts passed as th
2f8f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 e.** th
2f900 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68 ird parameter sh
2f910 61 6c 6c 20 62 65 20 5b 70 72 6f 74 65 63 74 65 all be [protecte
2f920 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2f930 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 objects..*/.int
2f940 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2f950 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 function(. sqli
2f960 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
2f970 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
2f980 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
2f990 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
2f9a0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
2f9b0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
2f9c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2f9d0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2f9e0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
2f9f0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
2fa00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
2fa10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
2fa20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
2fa30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2fa40 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
2fa50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
2fa60 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
2fa70 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a ,. const void *
2fa80 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
2fa90 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
2faa0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
2fab0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
2fac0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
2fad0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
2fae0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
2faf0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
2fb00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2fb10 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2fb20 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
2fb30 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
2fb40 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a context*).);../*
2fb50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
2fb60 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 xt Encodings {H1
2fb70 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 0267} <S50200> <
2fb80 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H16100>.**.** Th
2fb90 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 ese constant def
2fba0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
2fbb0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 s that represent
2fbc0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 the various.**
2fbd0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 text encodings s
2fbe0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
2fbf0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
2fc00 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 QLITE_UTF8
2fc10 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
2fc20 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 QLITE_UTF16LE
2fc30 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
2fc40 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 QLITE_UTF16BE
2fc50 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
2fc60 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 QLITE_UTF16
2fc70 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 4 /* Use
2fc80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
2fc90 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 er */.#define SQ
2fca0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 LITE_ANY
2fcb0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 5 /* sqli
2fcc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2fcd0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 ion only */.#def
2fce0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
2fcf0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f _ALIGNED 8 /
2fd00 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
2fd10 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 _collation only
2fd20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
2fd30 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 EF: Deprecated F
2fd40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 unctions.** DEPR
2fd50 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 ECATED.**.** The
2fd60 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
2fd70 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 [deprecated].
2fd80 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
2fd90 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
2fda0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
2fdb0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
2fdc0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
2fdd0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f continue .** to
2fde0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 be supported.
2fdf0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 However, new app
2fe00 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
2fe10 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 avoid.** the us
2fe20 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 e of these funct
2fe30 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 ions. To help e
2fe40 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 ncourage people
2fe50 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e to avoid.** usin
2fe60 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e g these function
2fe70 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f s, we are not go
2fe80 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 ing to tell you
2fe90 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f what they do..*/
2fea0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
2feb0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a OMIT_DEPRECATED.
2fec0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
2fed0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 D int sqlite3_ag
2fee0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
2fef0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
2ff00 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
2ff10 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 ED int sqlite3_e
2ff20 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 xpired(sqlite3_s
2ff30 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 tmt*);.SQLITE_DE
2ff40 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
2ff50 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 ite3_transfer_bi
2ff60 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 ndings(sqlite3_s
2ff70 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 tmt*, sqlite3_st
2ff80 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 mt*);.SQLITE_DEP
2ff90 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
2ffa0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 te3_global_recov
2ffb0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 er(void);.SQLITE
2ffc0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 _DEPRECATED void
2ffd0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f sqlite3_thread_
2ffe0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 cleanup(void);.S
2fff0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
30000 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d int sqlite3_mem
30010 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a ory_alarm(void(*
30020 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f )(void*,sqlite3_
30030 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a int64,int),void*
30040 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b ,sqlite3_int64);
30050 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
30060 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 API3REF: Obtaini
30070 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 ng SQL Function
30080 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 Parameter Values
30090 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 {H15100} <S2020
300a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 0>.**.** The C-l
300b0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
300c0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
300d0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
300e0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
300f0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
30100 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
30110 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
30120 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
30130 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
30140 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a or aggregate..**
30150 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 .** The xFunc (f
30160 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 or scalar functi
30170 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 ons) or xStep (f
30180 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 or aggregates) p
30190 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
301a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
301b0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
301c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
301d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
301e0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b define callback
301f0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
30200 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
30210 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
30220 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 s..** The 4th pa
30230 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 rameter to these
30240 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e callbacks is an
30250 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
30260 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 rs to.** [protec
30270 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
30280 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 e] objects. The
30290 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 re is one [sqlit
302a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
302b0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 for.** each par
302c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 ameter to the SQ
302d0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 L function. The
302e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
302f0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 used to.** extra
30300 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 ct values from t
30310 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
30320 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a e] objects..**.*
30330 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
30340 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 work only with
30350 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
30360 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30370 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 s..** Any attemp
30380 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 t to use these r
30390 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 outines on an [u
303a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
303b0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a e3_value].** obj
303c0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ect results in u
303d0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
303e0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 r..**.** These r
303f0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 outines work jus
30400 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 t like the corre
30410 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e sponding [column
30420 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
30430 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 s].** except tha
30440 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 t these routine
30450 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 s take a single
30460 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
30470 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30480 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 .** pointer inst
30490 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 ead of a [sqlite
304a0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 3_stmt*] pointer
304b0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 and an integer
304c0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a column number..*
304d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
304e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 _value_text16()
304f0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 interface extrac
30500 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 ts a UTF-16 stri
30510 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 ng.** in the nat
30520 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f ive byte-order o
30530 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 f the host machi
30540 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 ne. The.** sqli
30550 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
30560 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 be() and sqlite3
30570 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
30580 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
30590 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 extract UTF-16 s
305a0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e trings as big-en
305b0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d dian and little-
305c0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 endian respectiv
305d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
305e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
305f0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 eric_type() inte
30600 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
30610 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 o apply.** numer
30620 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 ic affinity to t
30630 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 he value. This
30640 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 means that an at
30650 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 tempt is.** made
30660 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
30670 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 value to an inte
30680 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 ger or floating
30690 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 point. If.** su
306a0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ch a conversion
306b0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 is possible with
306c0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f out loss of info
306d0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 rmation (in othe
306e0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 r.** words, if t
306f0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 he value is a st
30700 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 ring that looks
30710 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a like a number).*
30720 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 * then the conve
30730 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d rsion is perform
30740 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e ed. Otherwise n
30750 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 o conversion occ
30760 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c urs..** The [SQL
30770 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
30780 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
30790 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
307a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 rned..**.** Plea
307b0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 se pay particula
307c0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 r attention to t
307d0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 he fact that the
307e0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 pointer returne
307f0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
30800 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d e3_value_blob()]
30810 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
30820 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 _text()], or.**
30830 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
30840 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 ext16()] can be
30850 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 invalidated by a
30860 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
30870 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
30880 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 value_bytes()],
30890 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
308a0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 ytes16()], [sqli
308b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
308c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
308d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
308e0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ]..**.** These r
308f0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
30900 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
30910 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a same thread as.*
30920 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
30930 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 on that supplied
30940 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
30950 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 lue*] parameters
30960 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
30970 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 TS:.**.** {H1510
30980 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
30990 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 value_blob(V)] i
309a0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
309b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
309c0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c [protected sql
309d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
309e0 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 ct V into a BLOB
309f0 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 and then.**
30a00 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 returns a
30a10 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 pointer to the c
30a20 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a onverted value..
30a30 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 **.** {H15106} T
30a40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
30a50 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65 e_bytes(V)] inte
30a60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
30a70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 e.** nu
30a80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
30a90 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 the BLOB or str
30aa0 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f ing (exclusive o
30ab0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
30ac0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f zero terminato
30ad0 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 r on the string)
30ae0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e that was return
30af0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 ed by the.**
30b00 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e most recen
30b10 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
30b20 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 e3_value_blob(V)
30b30 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ] or.**
30b40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30b50 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 text(V)]..**.**
30b60 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71 {H15109} The [sq
30b70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
30b80 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 s16(V)] interfac
30b90 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a e returns the.**
30ba0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 number
30bb0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
30bc0 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 string (exclusi
30bd0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ve of the.**
30be0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 zero termi
30bf0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 nator on the str
30c00 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 ing) that was re
30c10 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
30c20 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 most r
30c30 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
30c40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
30c50 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 t16(V)],.**
30c60 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 [sqlite3_va
30c70 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d lue_text16be(V)]
30c80 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 , or [sqlite3_va
30c90 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d lue_text16le(V)]
30ca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d ..**.** {H15112}
30cb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
30cc0 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 lue_double(V)] i
30cd0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
30ce0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
30cf0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c [protected sql
30d00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
30d10 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 ct V into a floa
30d20 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
30d30 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
30d40 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
30d50 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a of that value..*
30d60 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 *.** {H15115} Th
30d70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
30d80 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61 _int(V)] interfa
30d90 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
30da0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f ** [pro
30db0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
30dc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 alue] object V i
30dd0 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 nto a 64-bit sig
30de0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a ned integer and.
30df0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
30e00 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 rns the lower 32
30e10 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e bits of that in
30e20 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 teger..**.** {H1
30e30 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 5118} The [sqlit
30e40 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 e3_value_int64(V
30e50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
30e60 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
30e70 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
30e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
30e90 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
30ea0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
30eb0 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 teger and.**
30ec0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 returns a
30ed0 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 copy of that int
30ee0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 eger..**.** {H15
30ef0 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 121} The [sqlite
30f00 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 3_value_text(V)]
30f10 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
30f20 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
30f30 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 [protected s
30f40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
30f50 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 ject V into a ze
30f60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
30f70 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 F-8.**
30f80 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
30f90 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
30fa0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a that string..**.
30fb0 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20 ** {H15124} The
30fc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
30fd0 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66 ext16(V)] interf
30fe0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
30ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
31000 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
31010 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 value] object V
31020 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d into a zero-term
31030 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a inated 2-byte.**
31040 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 aligne
31050 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 d UTF-16 native
31060 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 byte order.**
31070 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e string an
31080 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
31090 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 ter to that stri
310a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 ng..**.** {H1512
310b0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 7} The [sqlite3_
310c0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 value_text16be(V
310d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
310e0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
310f0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
31100 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
31110 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
31120 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
31130 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 2-byte.**
31140 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 aligned UTF-1
31150 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 6 big-endian.**
31160 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 string
31170 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
31180 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 inter to that st
31190 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 ring..**.** {H15
311a0 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 130} The [sqlite
311b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
311c0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 (V)] interface c
311d0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 onverts the.**
311e0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 [protect
311f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
31200 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 ] object V into
31210 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
31220 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 d 2-byte.**
31230 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 aligned UTF
31240 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
31250 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 n.** st
31260 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
31270 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
31280 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a at string..**.**
31290 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73 {H15133} The [s
312a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
312b0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(V)] interface
312c0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 returns.**
312d0 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 one of [SQLI
312e0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_NULL], [SQLIT
312f0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c E_INTEGER], [SQL
31300 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 ITE_FLOAT],.**
31310 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
31320 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 TEXT], or [SQLIT
31330 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f E_BLOB] as appro
31340 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 priate for.**
31350 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 the [sqli
31360 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
31370 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 t V..**.** {H151
31380 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 36} The [sqlite3
31390 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
313a0 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 ype(V)] interfac
313b0 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 e converts.**
313c0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74 the [prot
313d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
313e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e lue] object V in
313f0 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74 to either an int
31400 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 eger or.**
31410 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 a floating p
31420 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74 oint value if it
31430 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f can do so witho
31440 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 ut loss of.**
31450 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 informati
31460 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 on, and returns
31470 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e one of [SQLITE_N
31480 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ULL],.**
31490 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 [SQLITE_INTEGE
314a0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 R], [SQLITE_FLOA
314b0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 T], [SQLITE_TEXT
314c0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
314d0 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 [SQLITE_BLOB]
314e0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 as appropriate f
314f0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 or the.**
31500 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 [protected sq
31510 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
31520 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20 ect V after the
31530 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d conversion attem
31540 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 pt..*/.const voi
31550 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
31560 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
31570 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
31580 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 e3_value_bytes(s
31590 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
315a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
315b0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
315c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 3_value*);.doubl
315d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
315e0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 double(sqlite3_v
315f0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
31600 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
31610 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 lite3_value*);.s
31620 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
31630 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 ite3_value_int64
31640 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
31650 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
31660 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
31670 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
31680 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
31690 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
316a0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 alue_text16(sqli
316b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
316c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
316d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
316e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
316f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
31700 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
31710 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6be(sqlite3_valu
31720 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
31730 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 _value_type(sqli
31740 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
31750 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
31760 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 umeric_type(sqli
31770 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a te3_value*);../*
31780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
31790 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 tain Aggregate F
317a0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 unction Context
317b0 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30 {H16210} <S20200
317c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c >.**.** The impl
317d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 ementation of ag
317e0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
317f0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 tions use this r
31800 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 outine to alloca
31810 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 te.** a structur
31820 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 e for storing th
31830 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a eir state..**.**
31840 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 The first time
31850 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 the sqlite3_aggr
31860 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
31870 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
31880 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 d for a.** parti
31890 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c cular aggregate,
318a0 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 SQLite allocate
318b0 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f s nBytes of memo
318c0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 ry, zeroes out t
318d0 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 hat.** memory, a
318e0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 nd returns a poi
318f0 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 nter to it. On s
31900 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
31910 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a uent calls to.**
31920 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
31930 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 te_context() for
31940 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 the same aggreg
31950 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 ate function ind
31960 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 ex,.** the same
31970 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e buffer is return
31980 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e ed. The implemen
31990 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 tation of the ag
319a0 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a gregate can use.
319b0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 ** the returned
319c0 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 buffer to accumu
319d0 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a late data..**.**
319e0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 SQLite automati
319f0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 cally frees the
31a00 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 allocated buffer
31a10 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 when the aggreg
31a20 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e ate.** query con
31a30 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 cludes..**.** Th
31a40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
31a50 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f r should be a co
31a60 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 py of the.** [sq
31a70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 lite3_context |
31a80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e SQL function con
31a90 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 text] that is th
31aa0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
31ab0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c r.** to the call
31ac0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 back routine tha
31ad0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 t implements the
31ae0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
31af0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
31b00 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
31b10 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
31b20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
31b30 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 hich.** the aggr
31b40 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
31b50 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
31b60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
31b70 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 .**.** {H16211}
31b80 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 The first invoca
31b90 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
31ba0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
31bb0 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 xt(C,N)] for.**
31bc0 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69 a parti
31bd0 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f cular instance o
31be0 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 f an aggregate f
31bf0 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 unction (for a p
31c00 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 articular.**
31c10 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 context C)
31c20 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
31c30 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 o allocate N byt
31c40 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a es of memory,.**
31c50 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 zero t
31c60 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 hat memory, and
31c70 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 return a pointer
31c80 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 to the allocate
31c90 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 d memory..**.**
31ca0 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 {H16213} If a me
31cb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
31cc0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
31cd0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
31ce0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
31cf0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d te_context(C,N)]
31d00 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 then the functi
31d10 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a on returns 0..**
31d20 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63 .** {H16215} Sec
31d30 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
31d40 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f nt invocations o
31d50 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 f.** [s
31d60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
31d70 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 _context(C,N)] f
31d80 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 or the same cont
31d90 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a ext pointer C.**
31da0 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 ignore
31db0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
31dc0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f and return a po
31dd0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d inter to the sam
31de0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c e.** bl
31df0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 ock of memory re
31e00 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 turned by the fi
31e10 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a rst invocation..
31e20 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 **.** {H16217} T
31e30 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
31e40 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ted by [sqlite3_
31e50 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
31e60 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 t(C,N)] is.**
31e70 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 automatic
31e80 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 ally freed on th
31e90 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b e next call to [
31ea0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
31eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
31ec0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
31ed0 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 e()] for the [pr
31ee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
31ef0 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 ] containing.**
31f00 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67 the agg
31f10 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
31f20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
31f30 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f context C..*/.vo
31f40 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 id *sqlite3_aggr
31f50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 egate_context(sq
31f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
31f70 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a int nBytes);../*
31f80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 .** CAPI3REF: Us
31f90 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 er Data For Func
31fa0 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c tions {H16240} <
31fb0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20200>.**.** Th
31fc0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 e sqlite3_user_d
31fd0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
31fe0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
31ff0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
32000 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 that was the pU
32010 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 serData paramete
32020 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d r (the 5th param
32030 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
32040 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
32050 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
32060 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
32070 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
32080 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
32090 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
320a0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
320b0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
320c0 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a function. {END}.
320d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
320e0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
320f0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
32100 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
32110 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
32120 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
32130 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
32140 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
32150 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d :.**.** {H16243}
32160 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 The [sqlite3_us
32170 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65 er_data(C)] inte
32180 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
32190 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 copy of the.**
321a0 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65 P pointe
321b0 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 r from the [sqli
321c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
321d0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c ion(D,X,N,E,P,F,
321e0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 S,L)].**
321f0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 or [sqlite3_cr
32200 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
32210 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 D,X,N,E,P,F,S,L)
32220 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 ] call that.**
32230 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 register
32240 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ed the SQL funct
32250 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 ion associated w
32260 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e ith [sqlite3_con
32270 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 text] C..*/.void
32280 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 *sqlite3_user_d
32290 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
322a0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
322b0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
322c0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 Connection For
322d0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 Functions {H1625
322e0 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 0} <S60600><S202
322f0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
32300 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
32310 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 _handle() interf
32320 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
32330 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
32340 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
32350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
32360 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d ] (the 1st param
32370 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
32380 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
32390 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
323a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
323b0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
323c0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
323d0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
323e0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
323f0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
32400 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
32410 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
32420 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b * {H16253} The [
32430 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
32440 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e db_handle(C)] in
32450 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
32460 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
32470 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e D poin
32480 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ter from the [sq
32490 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
324a0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c ction(D,X,N,E,P,
324b0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 F,S,L)].**
324c0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f or [sqlite3_
324d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
324e0 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 6(D,X,N,E,P,F,S,
324f0 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a L)] call that.**
32500 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 regist
32510 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e ered the SQL fun
32520 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 ction associated
32530 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 with [sqlite3_c
32540 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 ontext] C..*/.sq
32550 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 lite3 *sqlite3_c
32560 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
32570 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32580 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
32590 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 REF: Function Au
325a0 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 xiliary Data {H1
325b0 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6270} <S20200>.*
325c0 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 *.** The followi
325d0 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 ng two functions
325e0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 may be used by
325f0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
32600 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 ions to.** assoc
32610 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 iate metadata wi
32620 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
32630 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
32640 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
32650 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
32660 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
32670 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
32680 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
32690 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
326a0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
326b0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
326c0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 ciated metadata
326d0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 may be preserved
326e0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 . This may.** be
326f0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 used, for examp
32700 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 le, to add a reg
32710 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 ular-expression
32720 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a matching scalar.
32730 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 ** function. The
32740 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f compiled versio
32750 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 n of the regular
32760 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 expression is s
32770 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 tored as.** meta
32780 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 data associated
32790 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c with the SQL val
327a0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ue passed as the
327b0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
327c0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 ion.** pattern.
327d0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 The compiled re
327e0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
327f0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f can be reused o
32800 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e n multiple.** in
32810 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
32820 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 same function s
32830 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 o that the origi
32840 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 nal pattern stri
32850 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e ng.** does not n
32860 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 eed to be recomp
32870 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 iled on each inv
32880 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 ocation..**.** T
32890 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 he sqlite3_get_a
328a0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
328b0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
328c0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 nter to the meta
328d0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 data.** associat
328e0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 ed by the sqlite
328f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
32900 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 function with th
32910 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a e Nth argument.*
32920 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 * value to the a
32930 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
32940 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 ed function. If
32950 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 no metadata has
32960 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 been ever.** bee
32970 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 n set for the Nt
32980 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 h argument of th
32990 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 e function, or i
329a0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 f the correspond
329b0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ing.** function
329c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 parameter has ch
329d0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 anged since the
329e0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 meta-data was se
329f0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 t,.** then sqlit
32a00 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
32a10 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
32a20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
32a30 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
32a40 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
32a50 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 ce saves the met
32a60 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 adata.** pointed
32a70 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 to by its 3rd p
32a80 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
32a90 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 metadata for the
32aa0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e N-th.** argumen
32ab0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 t of the applica
32ac0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
32ad0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 ction. Subseque
32ae0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 nt.** calls to s
32af0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
32b00 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 ta() might retur
32b10 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 n this data, if
32b20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 it has.** not be
32b30 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a en destroyed..**
32b40 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 If it is not NU
32b50 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 LL, SQLite will
32b60 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
32b70 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f uctor.** functio
32b80 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 n given by the 4
32b90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
32ba0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
32bb0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 ata() on.** the
32bc0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 metadata when th
32bd0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
32be0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 function paramet
32bf0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 er changes.** or
32c00 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 when the SQL st
32c10 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 atement complete
32c20 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d s, whichever com
32c30 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 es first..**.**
32c40 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 SQLite is free t
32c50 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 o call the destr
32c60 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d uctor and drop m
32c70 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a etadata on any.*
32c80 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 * parameter of a
32c90 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 ny function at a
32ca0 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e ny time. The on
32cb0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 ly guarantee is
32cc0 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 that.** the dest
32cd0 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 ructor will be c
32ce0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 alled before the
32cf0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f metadata is dro
32d00 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 pped..**.** In p
32d10 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 ractice, metadat
32d20 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 a is preserved b
32d30 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 etween function
32d40 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 calls for.** exp
32d50 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 ressions that ar
32d60 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f e constant at co
32d70 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 mpile time. This
32d80 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 includes litera
32d90 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 l.** values and
32da0 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a SQL variables..*
32db0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
32dc0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
32dd0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
32de0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
32df0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 .** the SQL func
32e00 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
32e10 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
32e20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 S:.**.** {H16272
32e30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 } The [sqlite3_g
32e40 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d et_auxdata(C,N)]
32e50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
32e60 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 ns a pointer.**
32e70 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 to meta
32e80 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 data associated
32e90 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 with the Nth par
32ea0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 ameter of the SQ
32eb0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 L function.**
32ec0 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e whose con
32ed0 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 text is C, or NU
32ee0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e LL if there is n
32ef0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 o metadata assoc
32f00 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 iated.**
32f10 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 with that para
32f20 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 meter..**.** {H1
32f30 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 6274} The [sqlit
32f40 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
32f50 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 ,N,P,D)] interfa
32f60 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 ce assigns a met
32f70 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 adata.**
32f80 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 pointer P to t
32f90 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 he Nth parameter
32fa0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 of the SQL func
32fb0 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 tion with contex
32fc0 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 t C..**.** {H162
32fd0 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 76} SQLite will
32fe0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
32ff0 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 uctor D with a s
33000 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a ingle argument.*
33010 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68 * which
33020 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 is the metadata
33030 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f pointer P follo
33040 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a wing a call to.*
33050 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
33060 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
33070 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 C,N,P,D)] when S
33080 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 QLite ceases to
33090 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 hold.**
330a0 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a the metadata..*
330b0 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 *.** {H16277} SQ
330c0 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 Lite ceases to h
330d0 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 old metadata for
330e0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e an SQL function
330f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 parameter.**
33100 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 when the
33110 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 value of that pa
33120 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e rameter changes.
33130 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 .**.** {H16278}
33140 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 When [sqlite3_se
33150 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c t_auxdata(C,N,P,
33160 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 D)] is invoked,
33170 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a the destructor.*
33180 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61 * is ca
33190 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 lled for any pri
331a0 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f or metadata asso
331b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
331c0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a same function.**
331d0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 contex
331e0 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 t C and paramete
331f0 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 r N..**.** {H162
33200 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 79} SQLite will
33210 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 call destructors
33220 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 for any metadat
33230 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a a it is holding.
33240 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 ** in a
33250 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 particular [pre
33260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
33270 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a S when either.*
33280 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
33290 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 te3_reset(S)] or
332a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
332b0 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 ze(S)] is called
332c0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
332d0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 e3_get_auxdata(s
332e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
332f0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 int N);.void sq
33300 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
33310 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
33320 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a t*, int N, void*
33330 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a , void (*)(void*
33340 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ));.../*.** CAPI
33350 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 3REF: Constants
33360 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c Defining Special
33370 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 Destructor Beha
33380 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 vior {H10280} <S
33390 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30100>.**.** The
333a0 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 se are special v
333b0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 alues for the de
333c0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 structor that is
333d0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
333e0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d e.** final argum
333f0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 ent to routines
33400 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 like [sqlite3_re
33410 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 sult_blob()]. I
33420 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 f the destructor
33430 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 .** argument is
33440 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 SQLITE_STATIC, i
33450 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
33460 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 content pointer
33470 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 is constant.**
33480 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 and will never c
33490 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 hange. It does
334a0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 not need to be d
334b0 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a estroyed. The.*
334c0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 * SQLITE_TRANSIE
334d0 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 NT value means t
334e0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
334f0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e will likely chan
33500 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 ge in.** the nea
33510 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 r future and tha
33520 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 t SQLite should
33530 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 make its own pri
33540 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 vate copy of.**
33550 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f the content befo
33560 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
33570 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 .** The typedef
33580 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 is necessary to
33590 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 work around prob
335a0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a lems in certain.
335b0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 ** C++ compilers
335c0 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 . See ticket #2
335d0 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 191..*/.typedef
335e0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 void (*sqlite3_d
335f0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 estructor_type)(
33600 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 void*);.#define
33610 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 SQLITE_STATIC
33620 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
33630 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a tructor_type)0).
33640 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
33650 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c RANSIENT ((sql
33660 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
33670 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 type)-1)../*.**
33680 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e CAPI3REF: Settin
33690 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 g The Result Of
336a0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 An SQL Function
336b0 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30 {H16400} <S20200
336c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f >.**.** These ro
336d0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
336e0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 by the xFunc or
336f0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 xFinal callbacks
33700 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 that.** impleme
33710 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 nt SQL functions
33720 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e and aggregates.
33730 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 See.** [sqlite
33740 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
33750 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 n()] and [sqlite
33760 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
33770 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 n16()].** for ad
33780 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
33790 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tion..**.** Thes
337a0 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b e functions work
337b0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 very much like
337c0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 the [parameter b
337d0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f inding] family o
337e0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 f.** functions u
337f0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 sed to bind valu
33800 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d es to host param
33810 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 eters in prepare
33820 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a d statements..**
33830 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 Refer to the [S
33840 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f QL parameter] do
33850 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
33860 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
33870 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 mation..**.** Th
33880 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
33890 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 _blob() interfac
338a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
338b0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
338c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
338d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
338e0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 the BLOB whose c
338f0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 ontent is pointe
33900 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 d.** to by the s
33910 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
33920 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 and which is N b
33930 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 ytes long where
33940 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 N is the.** thir
33950 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
33960 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
33970 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 esult_zeroblob()
33980 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 interfaces set
33990 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a the result of.**
339a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
339b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
339c0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 n to be a BLOB c
339d0 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 ontaining all ze
339e0 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 ro.** bytes and
339f0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c N bytes in size,
33a00 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
33a10 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 value of the 2nd
33a20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
33a30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
33a40 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e sult_double() in
33a50 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
33a60 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 result from.**
33a70 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
33a80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
33a90 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 to be a floating
33aa0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 point value spe
33ab0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 cified.** by its
33ac0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
33ad0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
33ae0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
33af0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
33b00 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e lt_error16() fun
33b10 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 ctions.** cause
33b20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 the implemented
33b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
33b40 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 throw an excepti
33b50 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 on..** SQLite us
33b60 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f es the string po
33b70 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a inted to by the.
33b80 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ** 2nd parameter
33b90 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 of sqlite3_resu
33ba0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 lt_error() or sq
33bb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33bc0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 or16().** as the
33bd0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f text of an erro
33be0 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 r message. SQLi
33bf0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 te interprets th
33c00 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
33c10 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 ge string from s
33c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
33c30 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 ror() as UTF-8.
33c40 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 SQLite.** interp
33c50 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 rets the string
33c60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 from sqlite3_res
33c70 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 ult_error16() as
33c80 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 UTF-16 in nativ
33c90 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e e.** byte order.
33ca0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 If the third p
33cb0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
33cc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
33cd0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
33ce0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
33cf0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 ) is negative th
33d00 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
33d10 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 as the error.**
33d20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 message all text
33d30 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 up through the
33d40 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
33d50 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 cter..** If the
33d60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
33d70 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
33d80 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 t_error() or.**
33d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33da0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d rror16() is non-
33db0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
33dc0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 Lite takes that
33dd0 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e many.** bytes (n
33de0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 ot characters) f
33df0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
33e00 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 meter as the err
33e10 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 or message..** T
33e20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33e30 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
33e40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33e50 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e or16().** routin
33e60 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 es make a privat
33e70 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 e copy of the er
33e80 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 ror message text
33e90 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 before.** they
33ea0 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 return. Hence,
33eb0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
33ec0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 tion can dealloc
33ed0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 ate or.** modify
33ee0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 the text after
33ef0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 they return with
33f00 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 out harm..** The
33f10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33f20 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e error_code() fun
33f30 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 ction changes th
33f40 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 e error code.**
33f50 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 returned by SQLi
33f60 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f te as a result o
33f70 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 f an error in a
33f80 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 function. By de
33f90 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 fault,.** the er
33fa0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 ror code is SQLI
33fb0 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 TE_ERROR. A sub
33fc0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 sequent call to
33fd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33fe0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
33ff0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
34000 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 r16() resets the
34010 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 error code to S
34020 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a QLITE_ERROR..**.
34030 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
34040 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 esult_toobig() i
34050 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
34060 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
34070 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 an error.** indi
34080 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 cating that a st
34090 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 ring or BLOB is
340a0 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 to long to repre
340b0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 sent..**.** The
340c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
340d0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 omem() interface
340e0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
340f0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 o throw an error
34100 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 .** indicating t
34110 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c hat a memory all
34120 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a ocation failed..
34130 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
34140 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 3_result_int() i
34150 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
34160 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
34170 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
34180 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
34190 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
341a0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
341b0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
341c0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
341d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
341e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
341f0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 int64() interfac
34200 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
34210 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
34220 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
34230 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
34240 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 o be the 64-bit
34250 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
34260 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
34270 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
34280 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c t..**.** The sql
34290 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
342a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
342b0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
342c0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
342d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
342e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
342f0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
34300 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
34310 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 ext(), sqlite3_r
34320 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a esult_text16(),.
34330 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
34340 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e t_text16le(), an
34350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
34360 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 _text16be() inte
34370 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 rfaces.** set th
34380 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
34390 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
343a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
343b0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 on to be.** a te
343c0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 xt string which
343d0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 is represented a
343e0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 s UTF-8, UTF-16
343f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
34400 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 r,.** UTF-16 lit
34410 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 tle endian, or U
34420 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e TF-16 big endian
34430 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a , respectively..
34440 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 ** SQLite takes
34450 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 the text result
34460 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 from the applica
34470 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 tion from.** the
34480 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
34490 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 f the sqlite3_re
344a0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
344b0 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 faces..** If the
344c0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
344d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
344e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
344f0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 faces.** is nega
34500 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 tive, then SQLit
34510 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 e takes result t
34520 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 ext from the 2nd
34530 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 parameter.** th
34540 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
34550 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
34560 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
34570 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
34580 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
34590 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
345a0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 * is non-negativ
345b0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 e, then as many
345c0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
345d0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 cters) of the te
345e0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f xt.** pointed to
345f0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
34600 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 meter are taken
34610 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 as the applicati
34620 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 on-defined.** fu
34630 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a nction result..*
34640 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 * If the 4th par
34650 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
34660 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
34670 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
34680 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
34690 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e lt_blob is a non
346a0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
346b0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
346c0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f that.** functio
346d0 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 n as the destruc
346e0 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 tor on the text
346f0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 or BLOB result w
34700 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 hen it has.** fi
34710 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
34720 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 t result..** If
34730 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
34740 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
34750 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
34760 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 terfaces or.** s
34770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
34780 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
34790 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
347a0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 E_STATIC, then S
347b0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 QLite.** assumes
347c0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f that the text o
347d0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 r BLOB result is
347e0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 in constant spa
347f0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a ce and does not.
34800 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f ** copy the it o
34810 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 r call a destruc
34820 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 tor when it has
34830 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
34840 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 hat result..** I
34850 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
34860 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
34870 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
34880 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
34890 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
348a0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 blob is the spec
348b0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c ial constant SQL
348c0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a ITE_TRANSIENT.**
348d0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b then SQLite mak
348e0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
348f0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 result into spa
34900 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ce obtained from
34910 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
34920 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 3_malloc()] befo
34930 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a re it returns..*
34940 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
34950 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
34960 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
34970 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
34980 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34990 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
349a0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 to be a copy th
349b0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 e.** [unprotecte
349c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
349d0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
349e0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 d by the 2nd par
349f0 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 ameter. The.**
34a00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
34a10 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
34a20 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
34a30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
34a40 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
34a50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
34a60 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
34a70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
34a80 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
34a90 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
34aa0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
34ab0 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
34ac0 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
34ad0 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 ..** A [protecte
34ae0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
34af0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 object may alwa
34b00 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 ys be used where
34b10 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
34b20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
34b30 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 e] object is req
34b40 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 uired, so either
34b50 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c .** kind of [sql
34b60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
34b70 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 ct can be used w
34b80 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 ith this interfa
34b90 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ce..**.** If the
34ba0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
34bb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 called from with
34bc0 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 in the different
34bd0 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 thread.** than
34be0 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 the one containi
34bf0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ng the applicati
34c00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
34c10 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 ion that receive
34c20 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 d.** the [sqlite
34c30 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 3_context] point
34c40 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 er, the results
34c50 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
34c60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
34c70 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 .**.** {H16403}
34c80 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 The default retu
34c90 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e rn value from an
34ca0 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 y SQL function i
34cb0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 s NULL..**.** {H
34cc0 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 16406} The [sqli
34cd0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
34ce0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 C,V,N,D)] interf
34cf0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
34d00 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
34d10 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
34d20 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42 tion C to be a B
34d30 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79 LOB that is N by
34d40 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 tes.**
34d50 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 in length and wi
34d60 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 th content point
34d70 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a ed to by V..**.*
34d80 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b * {H16409} The [
34d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
34da0 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 ouble(C,V)] inte
34db0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
34dc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
34dd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 turn value of fu
34de0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 nction C to be t
34df0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e he floating poin
34e00 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a t value V..**.**
34e10 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73 {H16412} The [s
34e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
34e30 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 ror(C,V,N)] inte
34e40 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
34e50 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 e return.**
34e60 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 value of fu
34e70 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 nction C to be a
34e80 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 n exception with
34e90 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 error code.**
34ea0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
34eb0 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 ERROR] and a UTF
34ec0 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 -8 error message
34ed0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 copied from V u
34ee0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 p to the.**
34ef0 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 first zero
34f00 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 byte or until N
34f10 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69 bytes are read i
34f20 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e f N is positive.
34f30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 .**.** {H16415}
34f40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
34f50 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c ult_error16(C,V,
34f60 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 N)] interface ch
34f70 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e anges the return
34f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
34f90 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
34fa0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 to be an except
34fb0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 ion with error c
34fc0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ode.**
34fd0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 [SQLITE_ERROR] a
34fe0 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 nd a UTF-16 nati
34ff0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 ve byte order er
35000 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 ror message.**
35010 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 copied f
35020 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 rom V up to the
35030 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
35040 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e nator or until N
35050 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 bytes.**
35060 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e are read if N
35070 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a is positive..**
35080 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65 .** {H16418} The
35090 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
350a0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 _error_toobig(C)
350b0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
350c0 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a ges the return.*
350d0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
350e0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
350f0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 C to be an exce
35100 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 ption with error
35110 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 code.**
35120 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 [SQLITE_TOOBIG
35130 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 ] and an appropr
35140 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 iate error messa
35150 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 ge..**.** {H1642
35160 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
35170 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d result_error_nom
35180 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 em(C)] interface
35190 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 changes the ret
351a0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
351b0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e value of the fun
351c0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e ction C to be an
351d0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 exception with
351e0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 error code.**
351f0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e [SQLITE_N
35200 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 OMEM] and an app
35210 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d ropriate error m
35220 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 essage..**.** {H
35230 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 16424} The [sqli
35240 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
35250 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 _code(C,E)] inte
35260 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
35270 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 e return.**
35280 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 value of th
35290 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 e function C to
352a0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 be an exception
352b0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 with error code
352c0 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 E..** T
352d0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
352e0 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 text is unchang
352f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 ed..**.** {H1642
35300 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 7} The [sqlite3_
35310 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d result_int(C,V)]
35320 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 interface chang
35330 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 es the.**
35340 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 return value
35350 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f of function C to
35360 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 be the 32-bit i
35370 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a nteger value V..
35380 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 **.** {H16430} T
35390 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
353a0 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 lt_int64(C,V)] i
353b0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
353c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
353d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
353e0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
353f0 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 e the 64-bit int
35400 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a eger value V..**
35410 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65 .** {H16433} The
35420 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35430 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 _null(C)] interf
35440 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
35450 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
35460 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
35470 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c tion C to be NUL
35480 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 L..**.** {H16436
35490 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
354a0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e esult_text(C,V,N
354b0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,D)] interface c
354c0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
354d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
354e0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
354f0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d C to be the UTF-
35500 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 8 string.**
35510 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 V up to the
35520 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e first zero if N
35530 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 is negative.**
35540 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 or the
35550 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 first N bytes of
35560 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e V if N is non-n
35570 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b egative..**.** {
35580 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c H16439} The [sql
35590 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
355a0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 16(C,V,N,D)] int
355b0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
355c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
355d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
355e0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
355f0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 the UTF-16 nativ
35600 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 e byte order.**
35610 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 string
35620 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 V up to the firs
35630 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e t zero if N is n
35640 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 egative.**
35650 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 or the first
35660 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 N bytes of V if
35670 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 N is non-negati
35680 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 ve..**.** {H1644
35690 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
356a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 result_text16be(
356b0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 C,V,N,D)] interf
356c0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
356d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
356e0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
356f0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 tion C to be the
35700 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 UTF-16 big-endi
35710 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 an.** s
35720 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 tring V up to th
35730 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 e first zero if
35740 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a N is negative.**
35750 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 or the
35760 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f first N bytes o
35770 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d r V if N is non-
35780 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 negative..**.**
35790 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 {H16445} The [sq
357a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
357b0 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 t16le(C,V,N,D)]
357c0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
357d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
357e0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f return value o
357f0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 f function C to
35800 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69 be the UTF-16 li
35810 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 ttle-endian.**
35820 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 string V
35830 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
35840 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 zero if N is ne
35850 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 gative.**
35860 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 or the first
35870 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 N bytes of V if
35880 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 N is non-negativ
35890 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 e..**.** {H16448
358a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
358b0 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 esult_value(C,V)
358c0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
358d0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
358e0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
358f0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
35900 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 o be the [unprot
35910 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
35920 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 lue].**
35930 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a object V..**.**
35940 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73 {H16451} The [s
35950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
35960 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 roblob(C,N)] int
35970 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
35980 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
35990 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
359a0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
359b0 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f an N-byte BLOB o
359c0 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a f all zeros..**.
359d0 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20 ** {H16454} The
359e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
359f0 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 error()] and [sq
35a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
35a10 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 or16()].**
35a20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d interfaces m
35a30 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ake a copy of th
35a40 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 eir error messag
35a50 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 e strings before
35a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
35a70 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 urning..**.** {H
35a80 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 16457} If the D
35a90 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d destructor param
35aa0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
35ab0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 _result_blob(C,V
35ac0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,N,D)],.**
35ad0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 [sqlite3_res
35ae0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 ult_text(C,V,N,D
35af0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 )], [sqlite3_res
35b00 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e ult_text16(C,V,N
35b10 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ,D)],.**
35b20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c [sqlite3_resul
35b30 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e t_text16be(C,V,N
35b40 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ,D)], or.**
35b50 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
35b60 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c sult_text16le(C,
35b70 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 V,N,D)] is the c
35b80 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f onstant [SQLITE_
35b90 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 STATIC].**
35ba0 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 then no dest
35bb0 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 ructor is ever c
35bc0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 alled on the poi
35bd0 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 nter V and SQLit
35be0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 e.** as
35bf0 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 sumes that V is
35c00 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a immutable..**.**
35c10 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65 {H16460} If the
35c20 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 D destructor pa
35c30 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
35c40 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
35c50 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 C,V,N,D)],.**
35c60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
35c70 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c result_text(C,V,
35c80 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f N,D)], [sqlite3_
35c90 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c result_text16(C,
35ca0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 V,N,D)],.**
35cb0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
35cc0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c sult_text16be(C,
35cd0 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 V,N,D)], or.**
35ce0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
35cf0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
35d00 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 (C,V,N,D)] is th
35d10 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 e constant.**
35d20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 [SQLITE_T
35d30 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 RANSIENT] then t
35d40 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 he interfaces ma
35d50 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
35d60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
35d70 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 ntent of V and r
35d80 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e etains the copy.
35d90 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 .**.** {H16463}
35da0 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 If the D destruc
35db0 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f tor parameter to
35dc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35dd0 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c _blob(C,V,N,D)],
35de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
35df0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
35e00 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 t(C,V,N,D)], [sq
35e10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
35e20 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a t16(C,V,N,D)],.*
35e30 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
35e40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
35e50 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 6be(C,V,N,D)], o
35e60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
35e70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
35e80 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d xt16le(C,V,N,D)]
35e90 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f is some value o
35ea0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 ther than.**
35eb0 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 the consta
35ec0 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 nts [SQLITE_STAT
35ed0 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f IC] and [SQLITE_
35ee0 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a TRANSIENT] then.
35ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 ** SQLi
35f00 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
35f10 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 he destructor D
35f20 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e with V as its on
35f30 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 ly argument.**
35f40 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 when it
35f50 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
35f60 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a h the V value..*
35f70 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
35f80 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 esult_blob(sqlit
35f90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
35fa0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
35fb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
35fc0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
35fd0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ult_double(sqlit
35fe0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 e3_context*, dou
35ff0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ble);.void sqlit
36000 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
36010 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
36020 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 , const char*, i
36030 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
36040 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
36050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
36060 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
36070 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
36080 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
36090 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 toobig(sqlite3_c
360a0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
360b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
360c0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 ror_nomem(sqlite
360d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
360e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
360f0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 _error_code(sqli
36100 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
36110 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
36120 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 _result_int(sqli
36130 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
36140 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
36150 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
36160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
36170 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
36180 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
36190 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ult_null(sqlite3
361a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
361b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
361c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
361d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
361e0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 r*, int, void(*)
361f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
36200 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
36210 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e xt16(sqlite3_con
36220 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
36230 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
36240 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
36250 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
36260 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
36270 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
36280 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
36290 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
362a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
362b0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
362c0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
362d0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
362e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
362f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36300 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f value(sqlite3_co
36310 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
36320 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 value*);.void sq
36330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
36340 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f oblob(sqlite3_co
36350 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a ntext*, int n);.
36360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36370 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c Define New Coll
36380 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 ating Sequences
36390 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30 {H16600} <S20300
363a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 >.**.** These fu
363b0 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 nctions are used
363c0 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c to add new coll
363d0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
363e0 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 to the.** [datab
363f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
36400 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 specified as the
36410 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
36420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 .**.** The name
36430 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 of the new colla
36440 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
36450 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 specified as a
36460 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
36470 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
36480 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 te_collation() a
36490 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nd sqlite3_creat
364a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
364b0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 .** and a UTF-16
364c0 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 string for sqli
364d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
364e0 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c tion16(). In all
364f0 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 cases.** the na
36500 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 me is passed as
36510 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 the second funct
36520 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ion argument..**
36530 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 .** The third ar
36540 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e gument may be on
36550 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
36560 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d ts [SQLITE_UTF8]
36570 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 ,.** [SQLITE_UTF
36580 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 16LE] or [SQLITE
36590 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 _UTF16BE], indic
365a0 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 ating that the u
365b0 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 ser-supplied.**
365c0 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 routine expects
365d0 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 to be passed poi
365e0 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
365f0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 encoded using U
36600 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 TF-8,.** UTF-16
36610 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f little-endian, o
36620 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 r UTF-16 big-end
36630 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
36640 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 y. The.** third
36650 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 argument might a
36660 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 lso be [SQLITE_U
36670 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f TF16_ALIGNED] to
36680 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a indicate that.*
36690 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 * the routine ex
366a0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 pects pointers t
366b0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c o 16-bit word al
366c0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a igned strings.**
366d0 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 of UTF-16 in th
366e0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
366f0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 der of the host
36700 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 computer..**.**
36710 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
36720 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 user supplied r
36730 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 outine must be p
36740 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 assed as the fif
36750 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 th.** argument.
36760 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 If it is NULL,
36770 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 this is the same
36780 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 as deleting the
36790 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
367a0 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 quence (so that
367b0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 SQLite cannot ca
367c0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a ll it anymore)..
367d0 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 ** Each time the
367e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 application sup
367f0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 plied function i
36800 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 s invoked, it is
36810 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 passed.** as it
36820 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
36830 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 r a copy of the
36840 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 void* passed as
36850 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
36860 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
36870 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36880 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f on() or sqlite3_
36890 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
368a0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 16()..**.** The
368b0 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 remaining argume
368c0 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 nts to the appli
368d0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 cation-supplied
368e0 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 routine are two
368f0 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 strings,.** each
36900 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
36910 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 a (length, data)
36920 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 pair and encode
36930 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e d in the encodin
36940 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 g.** that was pa
36950 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
36960 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 d argument when
36970 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 the collation se
36980 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 quence was.** re
36990 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 gistered. {END}
369a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
369b0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 defined collati
369c0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c on routine shoul
369d0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 d.** return nega
369e0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f tive, zero or po
369f0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 sitive if the fi
36a00 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 rst string is le
36a10 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 ss than,.** equa
36a20 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
36a30 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
36a40 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 string. i.e. (S
36a50 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 TRING1 - STRING2
36a60 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
36a70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
36a80 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 ation_v2() works
36a90 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 like sqlite3_cr
36aa0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
36ab0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
36ac0 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 it takes an extr
36ad0 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 a argument which
36ae0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
36af0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c for.** the coll
36b00 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 ation. The dest
36b10 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 ructor is called
36b20 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 when the collat
36b30 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f ion is.** destro
36b40 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 yed and is passe
36b50 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 d a copy of the
36b60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
36b70 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a void* pointer.*
36b80 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
36b90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
36ba0 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 n_v2()..** Colla
36bb0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f tions are destro
36bc0 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 yed when they ar
36bd0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
36be0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 later calls to t
36bf0 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 he.** collation
36c00 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f creation functio
36c10 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b ns or when the [
36c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
36c30 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a ion] is closed.*
36c40 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
36c50 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
36c60 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
36c70 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75 ** {H16603} A su
36c80 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
36c90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
36ca0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
36cb0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c _collation_v2(B,
36cc0 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 X,E,P,F,D)] inte
36cd0 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 rface.**
36ce0 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 registers func
36cf0 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f tion F as the co
36d00 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f mparison functio
36d10 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 n used to.**
36d20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 implement
36d30 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 collation X on t
36d40 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
36d50 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a nection] B for.*
36d60 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 * datab
36d70 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f ases having enco
36d80 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ding E..**.** {H
36d90 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 16604} SQLite un
36da0 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 derstands the X
36db0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
36dc0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
36dd0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36de0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
36df0 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 D)] as a zero-te
36e00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 rminated.**
36e10 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e UTF-8 strin
36e20 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 g in which case
36e30 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 is ignored for A
36e40 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20 SCII characters
36e50 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
36e60 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 is significant f
36e70 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 or non-ASCII cha
36e80 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b racters..**.** {
36e90 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 H16606} Successi
36ea0 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ve calls to [sql
36eb0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
36ec0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 ation_v2(B,X,E,P
36ed0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,F,D)].**
36ee0 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 with the same
36ef0 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 values for B, X
36f00 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 , and E, overrid
36f10 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a e prior values.*
36f20 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c * of P,
36f30 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a F, and D..**.**
36f40 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65 {H16609} If the
36f50 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e destructor D in
36f60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
36f70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c _collation_v2(B,
36f80 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 X,E,P,F,D)].**
36f90 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e is not N
36fa0 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 ULL then it is c
36fb0 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d alled with argum
36fc0 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a ent P when the.*
36fd0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 * colla
36fe0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
36ff0 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 dropped by SQLi
37000 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 te..**.** {H1661
37010 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 2} A collating f
37020 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 unction is dropp
37030 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 ed when it is ov
37040 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 erloaded..**.**
37050 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 {H16615} A colla
37060 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
37070 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 dropped when th
37080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
37090 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
370a0 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e is closed usin
370b0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 g [sqlite3_close
370c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 ()]..**.** {H166
370d0 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 18} The pointer
370e0 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 P in [sqlite3_cr
370f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
37100 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2(B,X,E,P,F,D)].
37110 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 ** is p
37120 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
37130 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
37140 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 eter to the comp
37150 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 arison.**
37160 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f function F fo
37170 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 r all subsequent
37180 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
37190 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 F..**.** {H16621
371a0 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c } A call to [sql
371b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
371c0 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 ation(B,X,E,P,F)
371d0 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 ] is exactly.**
371e0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d the sam
371f0 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b e as a call to [
37200 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
37210 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 ollation_v2()] w
37220 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ith.**
37230 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 the same paramet
37240 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 ers and a NULL d
37250 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a estructor..**.**
37260 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 {H16624} Follow
37270 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 ing a [sqlite3_c
37280 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
37290 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d v2(B,X,E,P,F,D)]
372a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 ,.** SQ
372b0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f Lite uses the co
372c0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f mparison functio
372d0 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 n F for all text
372e0 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 comparison.**
372f0 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f operatio
37300 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 ns on the [datab
37310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
37320 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 B on text values
37330 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
37340 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 use the collat
37350 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d ing sequence nam
37360 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ed X..**.** {H16
37370 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 627} The [sqlite
37380 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
37390 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d on16(B,X,E,P,F)]
373a0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a works the same.
373b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b ** as [
373c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
373d0 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 ollation(B,X,E,P
373e0 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 ,F)] except that
373f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
37400 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 collation name
37410 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 X is understood
37420 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 as UTF-16 in nat
37430 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a ive byte order.*
37440 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 * inste
37450 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a ad of UTF-8..**.
37460 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e ** {H16630} When
37470 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 multiple compar
37480 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 ison functions a
37490 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 re available for
374a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
374b0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 collating
374c0 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 sequence, SQLite
374d0 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 chooses the one
374e0 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f whose text enco
374f0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ding.**
37500 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 requires the le
37510 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f ast amount of co
37520 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 nversion from th
37530 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 e default.**
37540 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 text encod
37550 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 ing of the datab
37560 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ase..*/.int sqli
37570 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
37580 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a tion(. sqlite3*
37590 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
375a0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
375b0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
375c0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 *,. int(*xCompa
375d0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
375e0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
375f0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e nst void*).);.in
37600 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
37610 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
37620 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
37630 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
37640 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
37650 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e , . void*,. in
37660 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
37670 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
37680 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
37690 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 d*),. void(*xDe
376a0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b stroy)(void*).);
376b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
376c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
376d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
376e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d const void *zNam
376f0 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 e,. int eTextRe
37700 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 p, . void*,. i
37710 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
37720 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
37730 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
37740 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
37750 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 API3REF: Collati
37760 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 on Needed Callba
37770 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 cks {H16700} <S2
37780 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 0300>.**.** To a
37790 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 void having to r
377a0 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c egister all coll
377b0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
377c0 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 before a databas
377d0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 e.** can be used
377e0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 , a single callb
377f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 ack function may
37800 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 be registered w
37810 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 ith the.** [data
37820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
37830 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 to be called wh
37840 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 enever an undefi
37850 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a ned collation.**
37860 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 sequence is req
37870 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 uired..**.** If
37880 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
37890 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 registered using
378a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
378b0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 lation_needed()
378c0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 API,.** then it
378d0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 is passed the na
378e0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 mes of undefined
378f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
37900 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a nces as strings.
37910 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 ** encoded in UT
37920 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 F-8. {H16703} If
37930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
37940 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 on_needed16() is
37950 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 used,.** the na
37960 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 mes are passed a
37970 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 s UTF-16 in mach
37980 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 ine native byte
37990 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c order..** A call
379a0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 to either funct
379b0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 ion replaces any
379c0 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 existing callba
379d0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 ck..**.** When t
379e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 he callback is i
379f0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 nvoked, the firs
37a00 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 t argument passe
37a10 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f d is a copy.** o
37a20 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
37a30 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
37a40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
37a50 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 d() or.** sqlite
37a60 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
37a70 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 ed16(). The sec
37a80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
37a90 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
37aa0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 connection. The
37ab0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
37ac0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
37ad0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 E_UTF8], [SQLITE
37ae0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 _UTF16BE],.** or
37af0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
37b00 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ], indicating th
37b10 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 e most desirable
37b20 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c form of the col
37b30 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e lation.** sequen
37b40 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 ce function requ
37b50 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 ired. The fourt
37b60 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 h parameter is t
37b70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
37b80 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 * required colla
37b90 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a tion sequence..*
37ba0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
37bb0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c k function shoul
37bc0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 d register the d
37bd0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e esired collation
37be0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
37bf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
37c00 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ion()], [sqlite3
37c10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
37c20 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
37c30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
37c40 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a llation_v2()]..*
37c50 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
37c60 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 .**.** {H16702}
37c70 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
37c80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
37c90 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 llation_needed(D
37ca0 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,P,F)].**
37cb0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 or [sqlite3_c
37cc0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
37cd0 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 6(D,P,F)] causes
37ce0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
37cf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
37d00 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f ction] D to invo
37d10 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 ke callback F wi
37d20 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 th first.**
37d30 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 parameter P
37d40 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 whenever it nee
37d50 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 ds a comparison
37d60 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a function for a.*
37d70 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 * colla
37d80 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 ting sequence th
37d90 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b at it does not k
37da0 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a now about..**.**
37db0 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73 {H16704} Each s
37dc0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
37dd0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 o [sqlite3_colla
37de0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f tion_needed()] o
37df0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
37e00 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
37e10 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 _needed16()] ove
37e20 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 rrides the callb
37e30 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a ack registered.*
37e40 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 * on th
37e50 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
37e60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 connection] by
37e70 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 prior calls to e
37e80 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
37e90 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a interface..**.
37ea0 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20 ** {H16706} The
37eb0 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 name of the requ
37ec0 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 ested collating
37ed0 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 function passed
37ee0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 in the.**
37ef0 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 4th parameter
37f00 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
37f10 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 is in UTF-8 if
37f20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
37f30 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67 was reg
37f40 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 istered using [s
37f50 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
37f60 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a _needed()] and.*
37f70 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e * is in
37f80 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 UTF-16 native b
37f90 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 yte order if the
37fa0 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a callback was.**
37fb0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 regist
37fc0 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ered using [sqli
37fd0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
37fe0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e eded16()]..*/.in
37ff0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 t sqlite3_collat
38000 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 ion_needed(. sq
38010 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a lite3*, . void*
38020 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 , . void(*)(voi
38030 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
38040 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 eTextRep,const c
38050 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c har*).);.int sql
38060 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
38070 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 eeded16(. sqlit
38080 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 e3*, . void*,.
38090 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
380a0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
380b0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a tRep,const void*
380c0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 ).);../*.** Spec
380d0 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 ify the key for
380e0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 an encrypted dat
380f0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 abase. This rou
38100 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a tine should be.*
38110 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 * called right a
38120 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 fter sqlite3_ope
38130 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 n()..**.** The c
38140 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
38150 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
38160 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
38170 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
38180 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
38190 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 /.int sqlite3_ke
381a0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 y(. sqlite3 *db
381b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
381c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
381d0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
381e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 . const void *p
381f0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 Key, int nKey
38200 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a /* The key */.
38210 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 );../*.** Change
38220 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f the key on an o
38230 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 pen database. I
38240 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 f the current da
38250 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a tabase is not.**
38260 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 encrypted, this
38270 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e routine will en
38280 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e crypt it. If pN
38290 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 ew==0 or nNew==0
382a0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 , the.** databas
382b0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a e is decrypted..
382c0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
382d0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
382e0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
382f0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
38300 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
38310 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 f SQLite..*/.int
38320 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a sqlite3_rekey(.
38330 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
38340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38350 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
38360 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
38370 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
38380 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
38390 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f * The new key */
383a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
383b0 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 REF: Suspend Exe
383c0 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
383d0 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d rt Time {H10530}
383e0 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 <S40410>.**.**
383f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 The sqlite3_slee
38400 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 p() function cau
38410 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 ses the current
38420 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e thread to suspen
38430 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 d execution.** f
38440 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 or at least a nu
38450 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
38460 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 onds specified i
38470 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e n its parameter.
38480 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 .**.** If the op
38490 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 erating system d
384a0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 oes not support
384b0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 sleep requests w
384c0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f ith.** milliseco
384d0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 nd time resoluti
384e0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d on, then the tim
384f0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 e will be rounde
38500 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e d up to.** the n
38510 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 earest second. T
38520 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
38530 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
38540 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 ep actually.** r
38550 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 equested from th
38560 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
38570 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a em is returned..
38580 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 **.** SQLite imp
38590 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 lements this int
385a0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e erface by callin
385b0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a g the xSleep().*
385c0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 * method of the
385d0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
385e0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
385f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
38600 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 **.** {H10533} T
38610 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 he [sqlite3_slee
38620 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 p(M)] interface
38630 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 invokes the xSle
38640 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d ep.** m
38650 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
38660 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
38670 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 s|VFS] in order
38680 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 to.** s
38690 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
386a0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 of the current
386b0 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 thread for at le
386c0 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ast.**
386d0 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a M milliseconds..
386e0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 **.** {H10536} T
386f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 he [sqlite3_slee
38700 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 p(M)] interface
38710 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
38720 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 er of.**
38730 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f milliseconds o
38740 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 f sleep actually
38750 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 requested of th
38760 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 e operating.**
38770 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 system,
38780 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c which might be l
38790 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 arger than the p
387a0 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 arameter M..*/.i
387b0 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 nt sqlite3_sleep
387c0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
387d0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
387e0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 The Folder Holdi
387f0 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c ng Temporary Fil
38800 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 es {H10310} <S20
38810 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 000>.**.** If th
38820 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 is global variab
38830 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f le is made to po
38840 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
38850 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 which is.** the
38860 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 name of a folder
38870 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f (a.k.a. directo
38880 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 ry), then all te
38890 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a mporary files.**
388a0 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 created by SQLi
388b0 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 te will be place
388c0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 d in that direct
388d0 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 ory. If this va
388e0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e riable.** is a N
388f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
38900 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d n SQLite perform
38910 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 s a search for a
38920 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a n appropriate.**
38930 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 temporary file
38940 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a directory..**.**
38950 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
38960 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 to modify this v
38970 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b ariable once a [
38980 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
38990 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e ion].** has been
389a0 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 opened. It is
389b0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 intended that th
389c0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 is variable be s
389d0 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 et once.** as pa
389e0 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e rt of process in
389f0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
38a00 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 before any SQLi
38a10 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 te interface.**
38a20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 routines have be
38a30 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 en call and rema
38a40 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 in unchanged the
38a50 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 reafter..*/.SQLI
38a60 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a TE_EXTERN char *
38a70 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 sqlite3_temp_dir
38a80 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ectory;../*.** C
38a90 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f API3REF: Test Fo
38aa0 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f r Auto-Commit Mo
38ab0 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 de {H12930} <S60
38ac0 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 200>.** KEYWORDS
38ad0 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f : {autocommit mo
38ae0 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 de}.**.** The sq
38af0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
38b00 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 mmit() interface
38b10 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
38b20 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 o or.** zero if
38b30 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 the given databa
38b40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
38b50 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 or is not in au
38b60 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a tocommit mode,.*
38b70 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 * respectively.
38b80 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 Autocommit mode
38b90 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c is on by defaul
38ba0 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 t..** Autocommit
38bb0 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 mode is disable
38bc0 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 d by a [BEGIN] s
38bd0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 tatement..** Aut
38be0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
38bf0 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 re-enabled by a
38c00 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c [COMMIT] or [ROL
38c10 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 LBACK]..**.** If
38c20 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f certain kinds o
38c30 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f f errors occur o
38c40 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 n a statement wi
38c50 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 thin a multi-sta
38c60 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 tement.** transa
38c70 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e ction (errors in
38c80 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f cluding [SQLITE_
38c90 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 FULL], [SQLITE_I
38ca0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 OERR],.** [SQLIT
38cb0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 E_NOMEM], [SQLIT
38cc0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 E_BUSY], and [SQ
38cd0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 LITE_INTERRUPT])
38ce0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 then the.** tra
38cf0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 nsaction might b
38d00 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 e rolled back au
38d10 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 tomatically. Th
38d20 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a e only way to.**
38d30 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 find out whethe
38d40 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 r SQLite automat
38d50 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 ically rolled ba
38d60 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ck the transacti
38d70 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 on after.** an e
38d80 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 rror is to use t
38d90 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a his function..**
38da0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
38db0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54 **.** {H12931} T
38dc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f he [sqlite3_get_
38dd0 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 autocommit(D)] i
38de0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
38df0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 non-zero or.**
38e00 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66 zero if
38e10 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
38e20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 onnection] D is
38e30 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 or is not in aut
38e40 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 ocommit.**
38e50 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 mode, respec
38e60 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 tively..**.** {H
38e70 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 12932} Autocommi
38e80 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 t mode is on by
38e90 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b default..**.** {
38ea0 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d H12933} Autocomm
38eb0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 it mode is disab
38ec0 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 led by a success
38ed0 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 ful [BEGIN] stat
38ee0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ement..**.** {H1
38ef0 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 2934} Autocommit
38f00 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 mode is enabled
38f10 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c by a successful
38f20 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f [COMMIT] or [RO
38f30 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 LLBACK].**
38f40 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a statement..*
38f50 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 *.** ASSUMPTIONS
38f60 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d :.**.** {A12936}
38f70 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 If another thre
38f80 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 ad changes the a
38f90 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 utocommit status
38fa0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
38fb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
38fc0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
38fd0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 is routine is ru
38fe0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nning, then the
38ff0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
39000 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 is unde
39010 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 fined..*/.int sq
39020 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
39030 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a mmit(sqlite3*);.
39040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
39050 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 Find The Databa
39060 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 se Handle Of A P
39070 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
39080 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36 t {H13120} <S606
39090 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
390a0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 lite3_db_handle
390b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
390c0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
390d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
390e0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 le.** to which a
390f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
39100 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 ment] belongs.
39110 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e The database han
39120 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a dle returned by.
39130 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 ** sqlite3_db_ha
39140 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 ndle is the same
39150 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
39160 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 that was the fi
39170 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 rst argument.**
39180 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
39190 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 prepare_v2()] ca
391a0 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 ll (or its varia
391b0 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 nts) that was us
391c0 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 ed to.** create
391d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e the statement in
391e0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 the first place
391f0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
39200 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 TS:.**.** {H1312
39210 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
39220 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e db_handle(S)] in
39230 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
39240 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 a pointer.**
39250 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61 to the [da
39260 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
39270 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 n] associated wi
39280 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 th the.**
39290 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
392a0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 tement] S..*/.sq
392b0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 lite3 *sqlite3_d
392c0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 b_handle(sqlite3
392d0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
392e0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 CAPI3REF: Find t
392f0 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 he next prepared
39300 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 statement {H131
39310 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 40} <S60600>.**.
39320 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
39330 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
39340 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 ter to the next
39350 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
39360 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 ent] after.** pS
39370 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 tmt associated w
39380 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
39390 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 e connection] pD
393a0 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 b. If pStmt is
393b0 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 NULL.** then thi
393c0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
393d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
393e0 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 the first prepa
393f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
39400 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
39410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
39420 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 nnection pDb. I
39430 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 f no prepared st
39440 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 atement.** satis
39450 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 fies the conditi
39460 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ons of this rout
39470 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ine, it returns
39480 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 NULL..**.** INVA
39490 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
394a0 31 33 31 34 33 7d 20 49 66 20 44 20 69 73 20 61 13143} If D is a
394b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
394c0 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 ction] that hold
394d0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a s one or more.**
394e0 20 20 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61 unfina
394f0 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20 lized [prepared
39500 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 statements] and
39510 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e S is a NULL poin
39520 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ter,.**
39530 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e then [sqlite3_n
39540 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 ext_stmt(D, S)]
39550 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 routine shall re
39560 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a turn a pointer.*
39570 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e * to on
39580 65 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 e of the prepare
39590 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 d statements ass
395a0 6f 63 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a ociated with D..
395b0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49 **.** {H13146} I
395c0 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 f D is a [databa
395d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
395e0 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 hat holds no unf
395f0 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20 inalized.**
39600 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
39610 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 tatements] and S
39620 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
39630 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 er, then.**
39640 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 [sqlite3_ne
39650 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 xt_stmt(D, S)] r
39660 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 outine shall ret
39670 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 urn a NULL point
39680 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 er..**.** {H1314
39690 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70 72 9} If S is a [pr
396a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
396b0 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 ] in the [databa
396c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
396d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
396e0 20 53 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 S is not the la
396f0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 st prepared stat
39700 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e ement in D, then
39710 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
39720 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
39730 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 D, S)] routine s
39740 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f hall return a po
39750 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 inter.**
39760 20 20 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72 to the next pr
39770 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
39780 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a in D after S..*
39790 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66 *.** {H13152} If
397a0 20 53 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b S is the last [
397b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
397c0 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 nt] in the.**
397d0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
397e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 connection] D t
397f0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hen the [sqlite3
39800 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 _next_stmt(D, S)
39810 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f ].** ro
39820 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 utine shall retu
39830 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 rn a NULL pointe
39840 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 r..**.** ASSUMPT
39850 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 IONS:.**.** {A13
39860 31 35 34 7d 20 54 68 65 20 5b 64 61 74 61 62 61 154} The [databa
39870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
39880 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 ointer D in a ca
39890 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ll to.**
398a0 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f [sqlite3_next_
398b0 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 stmt(D,S)] must
398c0 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e refer to an open
398d0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 database.**
398e0 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e connection
398f0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c and in particul
39900 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 ar must not be a
39910 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
39920 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a /.sqlite3_stmt *
39930 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
39940 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 t(sqlite3 *pDb,
39950 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
39960 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
39970 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e I3REF: Commit An
39980 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 d Rollback Notif
39990 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ication Callback
399a0 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 s {H12950} <S604
399b0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
399c0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
399d0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
399e0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
399f0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 ck.** function t
39a00 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
39a10 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 never a transact
39a20 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 ion is committed
39a30 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
39a40 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
39a50 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ous call to sqli
39a60 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
39a70 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ).** for the sam
39a80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
39a90 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
39aa0 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 den..** The sqli
39ab0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
39ac0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
39ad0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
39ae0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 ck.** function t
39af0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
39b00 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 never a transact
39b10 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 ion is committed
39b20 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
39b30 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
39b40 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ous call to sqli
39b50 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
39b60 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ).** for the sam
39b70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
39b80 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
39b90 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 den..** The pArg
39ba0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 argument is pas
39bb0 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 sed through to t
39bc0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 he callback..**
39bd0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
39be0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b on a commit hook
39bf0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
39c00 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 s non-zero,.** t
39c10 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 hen the commit i
39c20 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f s converted into
39c30 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a a rollback..**.
39c40 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 ** If another fu
39c50 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 nction was previ
39c60 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 ously registered
39c70 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 , its.** pArg va
39c80 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
39c90 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c Otherwise NULL
39ca0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
39cb0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b .** The callback
39cc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
39cd0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
39ce0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
39cf0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
39d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
39d10 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
39d20 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 e callback. Any
39d30 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d actions.** to m
39d40 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 odify the databa
39d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
39d60 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 st be deferred u
39d70 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a ntil after the.*
39d80 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 * completion of
39d90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
39da0 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 p()] call that t
39db0 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d riggered the com
39dc0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 mit.** or rollba
39dd0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 ck hook in the f
39de0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e irst place..** N
39df0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
39e00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
39e10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
39e20 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
39e30 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
39e40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
39e50 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
39e60 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
39e70 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
39e80 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 .** Registering
39e90 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 a NULL function
39ea0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c disables the cal
39eb0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 lback..**.** For
39ec0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
39ed0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 this API, a tra
39ee0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 nsaction is said
39ef0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a to have been.**
39f00 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 rolled back if
39f10 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c an explicit "ROL
39f20 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 LBACK" statement
39f30 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 is executed, or
39f40 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 .** an error or
39f50 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 constraint cause
39f60 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f s an implicit ro
39f70 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e llback to occur.
39f80 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b .** The rollback
39f90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
39fa0 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 invoked if a tr
39fb0 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 ansaction is.**
39fc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f automatically ro
39fd0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
39fe0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
39ff0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
3a000 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c sed..** The roll
3a010 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 back callback is
3a020 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 not invoked if
3a030 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
3a040 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 .** rolled back
3a050 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 because a commit
3a060 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
3a070 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 ed non-zero..**
3a080 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 <todo> Check on
3a090 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a this </todo>.**.
3a0a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
3a0b0 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54 68 *.** {H12951} Th
3a0c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 e [sqlite3_commi
3a0d0 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 t_hook(D,F,P)] i
3a0e0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
3a0f0 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 rs the.**
3a100 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 callback func
3a110 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 tion F to be inv
3a120 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 oked with argume
3a130 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a nt P whenever.**
3a140 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e a tran
3a150 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 saction commits
3a160 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
3a170 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a connection] D..
3a180 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54 **.** {H12952} T
3a190 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d he [sqlite3_comm
3a1a0 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 it_hook(D,F,P)]
3a1b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
3a1c0 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 s the P argument
3a1d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f .** fro
3a1e0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 m the previous c
3a1f0 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d all with the sam
3a200 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
3a210 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 ection] D,.**
3a220 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f or NULL o
3a230 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c n the first call
3a240 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
3a250 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
3a260 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b ction D..**.** {
3a270 48 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c H12953} Each cal
3a280 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
3a290 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 mmit_hook()] ove
3a2a0 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c rwrites the call
3a2b0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 back.**
3a2c0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70 registered by p
3a2d0 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a rior calls..**.*
3a2e0 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 20 74 68 * {H12954} If th
3a2f0 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 e F argument to
3a300 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f [sqlite3_commit_
3a310 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 hook(D,F,P)] is
3a320 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 NULL.**
3a330 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 then the commit
3a340 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 hook callback i
3a350 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e s canceled and n
3a360 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 o callback.**
3a370 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 is invoke
3a380 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 d when a transac
3a390 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a tion commits..**
3a3a0 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49 66 20 .** {H12955} If
3a3b0 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 the commit callb
3a3c0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
3a3d0 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f zero then the co
3a3e0 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 mmit is.**
3a3f0 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e converted in
3a400 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a to a rollback..*
3a410 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54 68 *.** {H12961} Th
3a420 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 e [sqlite3_rollb
3a430 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d ack_hook(D,F,P)]
3a440 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
3a450 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 ters the.**
3a460 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 callback fu
3a470 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 nction F to be i
3a480 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 nvoked with argu
3a490 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a ment P whenever.
3a4a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 ** a tr
3a4b0 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 ansaction rolls
3a4c0 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74 back on the [dat
3a4d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a4e0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ] D..**.** {H129
3a4f0 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 62} The [sqlite3
3a500 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 _rollback_hook(D
3a510 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
3a520 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a returns the P.*
3a530 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d * argum
3a540 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 ent from the pre
3a550 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 vious call with
3a560 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 the same.**
3a570 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 [database c
3a580 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 onnection] D, or
3a590 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 NULL on the fir
3a5a0 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 st call.**
3a5b0 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 for a partic
3a5c0 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f ular database co
3a5d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a nnection D..**.*
3a5e0 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 63 68 20 * {H12963} Each
3a5f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
3a600 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 _rollback_hook()
3a610 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 ] overwrites the
3a620 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 callback.**
3a630 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 registered
3a640 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e by prior calls.
3a650 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20 .**.** {H12964}
3a660 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e If the F argumen
3a670 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f t to [sqlite3_ro
3a680 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c llback_hook(D,F,
3a690 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 P)] is NULL.**
3a6a0 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 then the
3a6b0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 rollback hook c
3a6c0 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 allback is cance
3a6d0 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 led and no callb
3a6e0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ack.**
3a6f0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
3a700 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f a transaction ro
3a710 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 lls back..*/.voi
3a720 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 d *sqlite3_commi
3a730 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c t_hook(sqlite3*,
3a740 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
3a750 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 void*);.void *sq
3a760 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
3a770 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ook(sqlite3*, vo
3a780 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 id(*)(void *), v
3a790 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
3a7a0 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 PI3REF: Data Cha
3a7b0 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e nge Notification
3a7c0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 Callbacks {H129
3a7d0 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 70} <S60400>.**.
3a7e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
3a7f0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 pdate_hook() int
3a800 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
3a810 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
3a820 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 tion.** with the
3a830 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3a840 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 ction] identifie
3a850 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
3a860 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 rgument.** to be
3a870 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
3a880 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 r a row is updat
3a890 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
3a8a0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 deleted..** Any
3a8b0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
3a8c0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
3a8d0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
3a8e0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
3a8f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3a900 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 tion is overridd
3a910 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 en..**.** The se
3a920 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
3a930 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
3a940 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e e function to in
3a950 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 voke when a.** r
3a960 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 ow is updated, i
3a970 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
3a980 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ed..** The first
3a990 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3a9a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
3a9b0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
3a9c0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
3a9d0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
3a9e0 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 ook()..** The se
3a9f0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 cond callback ar
3aa00 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
3aa10 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d [SQLITE_INSERT]
3aa20 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 , [SQLITE_DELETE
3aa30 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
3aa40 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 _UPDATE], depend
3aa50 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 ing on the opera
3aa60 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 tion that caused
3aa70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a the callback.**
3aa80 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a to be invoked..
3aa90 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 ** The third and
3aaa0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
3aab0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
3aac0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
3aad0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 rs to the.** dat
3aae0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 abase and table
3aaf0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 name containing
3ab00 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 the affected row
3ab10 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 ..** The final c
3ab20 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
3ab30 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d r is the [rowid]
3ab40 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 of the row..**
3ab50 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 In the case of a
3ab60 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 n update, this i
3ab70 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 s the [rowid] af
3ab80 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 ter the update t
3ab90 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a akes place..**.*
3aba0 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f * The update hoo
3abb0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
3abc0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 when internal s
3abd0 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 ystem tables are
3abe0 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e .** modified (i.
3abf0 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 e. sqlite_master
3ac00 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 and sqlite_sequ
3ac10 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ence)..**.** The
3ac20 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 update hook imp
3ac30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 lementation must
3ac40 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
3ac50 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
3ac60 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
3ac70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
3ac80 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 t invoked the up
3ac90 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 date hook. Any
3aca0 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f actions.** to mo
3acb0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 dify the databas
3acc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 e connection mus
3acd0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e t be deferred un
3ace0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a til after the.**
3acf0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 completion of t
3ad00 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
3ad10 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ()] call that tr
3ad20 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 iggered the upda
3ad30 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 te hook..** Note
3ad40 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
3ad50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
3ad60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
3ad70 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
3ad80 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
3ad90 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
3ada0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
3adb0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
3adc0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
3add0 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
3ade0 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
3adf0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
3ae00 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a its pArg value.*
3ae10 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 * is returned.
3ae20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 Otherwise NULL i
3ae30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
3ae40 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
3ae50 0a 2a 2a 20 7b 48 31 32 39 37 31 7d 20 54 68 65 .** {H12971} The
3ae60 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 [sqlite3_update
3ae70 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e _hook(D,F,P)] in
3ae80 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
3ae90 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 he callback.**
3aea0 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e function
3aeb0 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 F to be invoked
3aec0 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61 with first para
3aed0 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 meter P whenever
3aee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 .** a t
3aef0 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 able row is modi
3af00 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 fied, inserted,
3af10 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a or deleted on.**
3af20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 the [d
3af30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3af40 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 on] D..**.** {H1
3af50 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 2973} The [sqlit
3af60 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 e3_update_hook(D
3af70 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
3af80 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c returns the val
3af90 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ue.** o
3afa0 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 f P for the prev
3afb0 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 ious call on the
3afc0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
3afd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a connection] D,.*
3afe0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 * or NU
3aff0 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 LL for the first
3b000 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 call..**.** {H1
3b010 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 2975} If the upd
3b020 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 ate hook callbac
3b030 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f k F in [sqlite3_
3b040 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c update_hook(D,F,
3b050 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 P)].**
3b060 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
3b070 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 no update callb
3b080 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a acks are made..*
3b090 2a 0a 2a 2a 20 7b 48 31 32 39 37 37 7d 20 45 61 *.** {H12977} Ea
3b0a0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
3b0b0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
3b0c0 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 D,F,P)] override
3b0d0 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a s prior calls.**
3b0e0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
3b0f0 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 same interface
3b100 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 on the same [dat
3b110 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3b120 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ] D..**.** {H129
3b130 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 79} The update h
3b140 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ook callback is
3b150 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
3b160 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d internal system
3b170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 .** tab
3b180 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 les such as sqli
3b190 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 te_master and sq
3b1a0 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 lite_sequence ar
3b1b0 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a e modified..**.*
3b1c0 2a 20 7b 48 31 32 39 38 31 7d 20 54 68 65 20 73 * {H12981} The s
3b1d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
3b1e0 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61 to the update ca
3b1f0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 llback.**
3b200 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 is one of [SQ
3b210 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 LITE_INSERT], [S
3b220 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 QLITE_DELETE] or
3b230 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d [SQLITE_UPDATE]
3b240 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 ,.** de
3b250 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
3b260 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 peration that ca
3b270 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 used the callbac
3b280 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e k to be invoked.
3b290 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 33 7d 20 .**.** {H12983}
3b2a0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
3b2b0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 urth arguments t
3b2c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 o the callback c
3b2d0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a ontain pointers.
3b2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a ** to z
3b2f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
3b300 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 TF-8 strings whi
3b310 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 ch are the names
3b320 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
3b330 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 database and
3b340 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 table that is b
3b350 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a eing updated...*
3b360 2a 20 7b 48 31 32 39 38 35 7d 20 54 68 65 20 66 * {H12985} The f
3b370 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 inal callback pa
3b380 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
3b390 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f rowid] of the ro
3b3a0 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 w after.**
3b3b0 20 20 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f the change o
3b3c0 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a ccurs..*/.void *
3b3d0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
3b3e0 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ook(. sqlite3*,
3b3f0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 . void(*)(void
3b400 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e *,int ,char con
3b410 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 st *,char const
3b420 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 *,sqlite3_int64)
3b430 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a ,. void*.);../*
3b440 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
3b450 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
3b460 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 Shared Pager Cac
3b470 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30 he {H10330} <S30
3b480 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 900>.** KEYWORDS
3b490 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d : {shared cache}
3b4a0 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d {shared cache m
3b4b0 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ode}.**.** This
3b4c0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
3b4d0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 or disables the
3b4e0 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 sharing of the d
3b4f0 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a atabase cache.**
3b500 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 and schema data
3b510 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 structures betw
3b520 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f een [database co
3b530 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 nnection | conne
3b540 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 ctions].** to th
3b550 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e e same database.
3b560 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 Sharing is enab
3b570 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d led if the argum
3b580 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 ent is true.** a
3b590 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 nd disabled if t
3b5a0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 he argument is f
3b5b0 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 alse..**.** Cach
3b5c0 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 e sharing is ena
3b5d0 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 bled and disable
3b5e0 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 d for an entire
3b5f0 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 0a 2a process. {END}.*
3b600 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e * This is a chan
3b610 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 ge as of SQLite
3b620 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 version 3.5.0. I
3b630 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 n prior versions
3b640 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 of SQLite,.** s
3b650 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c haring was enabl
3b660 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 ed or disabled f
3b670 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 or each thread s
3b680 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a eparately..**.**
3b690 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 The cache shari
3b6a0 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 ng mode set by t
3b6b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 his interface ef
3b6c0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 fects all subseq
3b6d0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f uent.** calls to
3b6e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
3b6f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
3b700 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c _v2()], and [sql
3b710 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a ite3_open16()]..
3b720 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 ** Existing data
3b730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
3b740 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 continue use th
3b750 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a e sharing mode.*
3b760 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 * that was in ef
3b770 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 fect at the time
3b780 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 they were opene
3b790 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c d..**.** Virtual
3b7a0 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 tables cannot b
3b7b0 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68 e used with a sh
3b7c0 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 65 ared cache. Whe
3b7d0 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 n shared.** cach
3b7e0 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 e is enabled, th
3b7f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
3b800 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 e_module()] API
3b810 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 used to register
3b820 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c .** virtual tabl
3b830 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 es will always r
3b840 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a eturn an error..
3b850 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
3b860 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
3b870 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 TE_OK] if shared
3b880 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c cache was enabl
3b890 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a ed or disabled.*
3b8a0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
3b8b0 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d An [error code]
3b8c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 is returned oth
3b8d0 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 erwise..**.** Sh
3b8e0 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 ared cache is di
3b8f0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
3b900 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 t. But this migh
3b910 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 t change in.** f
3b920 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
3b930 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 f SQLite. Appli
3b940 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 cations that car
3b950 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a e about shared.*
3b960 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 * cache setting
3b970 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 should set it ex
3b980 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 plicitly..**.**
3b990 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
3b9a0 2a 20 7b 48 31 30 33 33 31 7d 20 41 20 73 75 63 * {H10331} A suc
3b9b0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
3b9c0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 on of [sqlite3_e
3b9d0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
3b9e0 68 65 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 he(B)].**
3b9f0 20 20 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f will enable o
3ba00 72 20 64 69 73 61 62 6c 65 20 73 68 61 72 65 64 r disable shared
3ba10 20 63 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 cache mode for
3ba20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79 any subsequently
3ba30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 .** cre
3ba40 61 74 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 ated [database c
3ba50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 onnection] in th
3ba60 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a e same process..
3ba70 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 36 7d 20 57 **.** {H10336} W
3ba80 68 65 6e 20 73 68 61 72 65 64 20 63 61 63 68 65 hen shared cache
3ba90 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 is enabled, the
3baa0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
3bab0 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 _module()].**
3bac0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 interface
3bad0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
3bae0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a urn an error..**
3baf0 0a 2a 2a 20 7b 48 31 30 33 33 37 7d 20 54 68 65 .** {H10337} The
3bb00 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
3bb10 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 _shared_cache(B)
3bb20 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
3bb30 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rns.**
3bb40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 [SQLITE_OK] if s
3bb50 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 hared cache was
3bb60 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 enabled or disab
3bb70 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 led successfully
3bb80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 39 7d ..**.** {H10339}
3bb90 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 Shared cache is
3bba0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
3bbb0 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ault..*/.int sql
3bbc0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
3bbd0 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a ed_cache(int);..
3bbe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3bbf0 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 Attempt To Free
3bc00 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 Heap Memory {H17
3bc10 33 34 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 340} <S30220>.**
3bc20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
3bc30 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
3bc40 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
3bc50 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 pts to free N by
3bc60 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d tes.** of heap m
3bc70 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 emory by dealloc
3bc80 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 ating non-essent
3bc90 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ial memory alloc
3bca0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 ations.** held b
3bcb0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c y the database l
3bcc0 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d ibrary. {END} M
3bcd0 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 emory used to ca
3bce0 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 che database.**
3bcf0 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 pages to improve
3bd00 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 performance is
3bd10 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f an example of no
3bd20 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f n-essential memo
3bd30 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 ry..** sqlite3_r
3bd40 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 elease_memory()
3bd50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
3bd60 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 er of bytes actu
3bd70 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 ally freed,.** w
3bd80 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f hich might be mo
3bd90 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 re or less than
3bda0 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 the amount reque
3bdb0 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 sted..**.** INVA
3bdc0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
3bdd0 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 17341} The [sqli
3bde0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
3bdf0 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 ry(N)] interface
3be00 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 attempts to.**
3be10 20 20 20 20 20 20 20 20 20 66 72 65 65 20 4e 20 free N
3be20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 bytes of heap me
3be30 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 mory by dealloca
3be40 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 ting non-essenti
3be50 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d al.** m
3be60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
3be70 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 s held by the da
3be80 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 0a tabase library..
3be90 2a 2a 0a 2a 2a 20 7b 48 31 36 33 34 32 7d 20 54 **.** {H16342} T
3bea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 he [sqlite3_rele
3beb0 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 ase_memory(N)] r
3bec0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
3bed0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 r.** of
3bee0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 bytes actually
3bef0 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 freed, which mig
3bf00 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 ht be more or le
3bf10 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ss.** t
3bf20 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 han the amount r
3bf30 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 equested..*/.int
3bf40 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
3bf50 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f _memory(int);../
3bf60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
3bf70 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e mpose A Limit On
3bf80 20 48 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33 Heap Size {H173
3bf90 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 50} <S30220>.**.
3bfa0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ** The sqlite3_s
3bfb0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 oft_heap_limit()
3bfc0 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 interface place
3bfd0 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 s a "soft" limit
3bfe0 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e .** on the amoun
3bff0 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 t of heap memory
3c000 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c that may be all
3c010 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 ocated by SQLite
3c020 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 ..** If an inter
3c030 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 nal allocation i
3c040 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61 74 s requested that
3c050 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 would exceed th
3c060 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c e.** soft heap l
3c070 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 imit, [sqlite3_r
3c080 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d elease_memory()]
3c090 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 is invoked one
3c0a0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 or.** more times
3c0b0 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 to free up some
3c0c0 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 space before th
3c0d0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 e allocation is
3c0e0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a performed..**.**
3c0f0 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 The limit is ca
3c100 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 lled "soft", bec
3c110 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 ause if [sqlite3
3c120 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
3c130 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 )].** cannot fre
3c140 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d e sufficient mem
3c150 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 ory to prevent t
3c160 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 he limit from be
3c170 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a ing exceeded,.**
3c180 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 the memory is a
3c190 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 llocated anyway
3c1a0 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 and the current
3c1b0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 operation procee
3c1c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 ds..**.** A nega
3c1d0 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c tive or zero val
3c1e0 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 ue for N means t
3c1f0 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hat there is no
3c200 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
3c210 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
3c220 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
3c230 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 ] will only be c
3c240 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 alled when memor
3c250 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a y is exhausted..
3c260 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 ** The default v
3c270 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 alue for the sof
3c280 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
3c290 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 zero..**.** SQLi
3c2a0 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 te makes a best
3c2b0 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 effort to honor
3c2c0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
3c2d0 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 mit..** But if t
3c2e0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
3c2f0 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e it cannot be hon
3c300 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 ored, execution
3c310 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 will.** continue
3c320 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f without error o
3c330 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 r notification.
3c340 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 This is why the
3c350 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c limit is.** cal
3c360 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d led a "soft" lim
3c370 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 it. It is advis
3c380 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ory only..**.**
3c390 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 Prior to SQLite
3c3a0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 version 3.5.0, t
3c3b0 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 his routine only
3c3c0 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 constrained the
3c3d0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
3c3e0 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 ated by a single
3c3f0 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 thread - the sa
3c400 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 me thread in whi
3c410 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a ch this routine.
3c420 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e ** runs. Beginn
3c430 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 ing with SQLite
3c440 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 version 3.5.0, t
3c450 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
3c460 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 it is.** applied
3c470 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e to all threads.
3c480 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 The value speci
3c490 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 fied for the sof
3c4a0 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 t heap limit.**
3c4b0 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e is an upper boun
3c4c0 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d d on the total m
3c4d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
3c4e0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 for all threads
3c4f0 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 . In.** version
3c500 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 3.5.0 there is n
3c510 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 o mechanism for
3c520 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 limiting the hea
3c530 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 p usage for.** i
3c540 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 ndividual thread
3c550 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 s..**.** INVARIA
3c560 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 NTS:.**.** {H163
3c570 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 51} The [sqlite3
3c580 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
3c590 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 70 (N)] interface p
3c5a0 6c 61 63 65 73 20 61 20 73 6f 66 74 20 6c 69 6d laces a soft lim
3c5b0 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f it.** o
3c5c0 66 20 4e 20 62 79 74 65 73 20 6f 6e 20 74 68 65 f N bytes on the
3c5d0 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 amount of heap
3c5e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 memory that may
3c5f0 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 be allocated.**
3c600 20 20 20 20 20 20 20 20 20 75 73 69 6e 67 20 5b using [
3c610 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
3c620 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
3c630 61 6c 6c 6f 63 28 29 5d 20 61 74 20 61 6e 79 20 alloc()] at any
3c640 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 point.**
3c650 20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a in time..**.**
3c660 20 7b 48 31 36 33 35 32 7d 20 49 66 20 61 20 63 {H16352} If a c
3c670 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
3c680 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 malloc()] or [sq
3c690 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
3c6a0 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 20 20 would.**
3c6b0 20 20 20 63 61 75 73 65 20 74 68 65 20 74 6f 74 cause the tot
3c6c0 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c al amount of all
3c6d0 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 20 74 6f ocated memory to
3c6e0 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 20 exceed the.**
3c6f0 20 20 20 20 20 20 20 20 73 6f 66 74 20 68 65 61 soft hea
3c700 70 20 6c 69 6d 69 74 2c 20 74 68 65 6e 20 5b 73 p limit, then [s
3c710 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
3c720 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f emory()] is invo
3c730 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ked.**
3c740 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f in an attempt to
3c750 20 72 65 64 75 63 65 20 74 68 65 20 6d 65 6d 6f reduce the memo
3c760 72 79 20 75 73 61 67 65 20 70 72 69 6f 72 20 74 ry usage prior t
3c770 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 o proceeding.**
3c780 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 with th
3c790 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
3c7a0 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a ion attempt..**.
3c7b0 2a 2a 20 7b 48 31 36 33 35 33 7d 20 43 61 6c 6c ** {H16353} Call
3c7c0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 s to [sqlite3_ma
3c7d0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 lloc()] or [sqli
3c7e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 te3_realloc()] t
3c7f0 68 61 74 20 74 72 69 67 67 65 72 0a 2a 2a 20 20 hat trigger.**
3c800 20 20 20 20 20 20 20 20 61 74 74 65 6d 70 74 73 attempts
3c810 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 to reduce memor
3c820 79 20 75 73 61 67 65 20 74 68 72 6f 75 67 68 20 y usage through
3c830 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
3c840 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 mit.**
3c850 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e mechanism contin
3c860 75 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 61 ue even if the a
3c870 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 ttempt to reduce
3c880 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 memory.**
3c890 20 20 20 20 75 73 61 67 65 20 69 73 20 75 6e 73 usage is uns
3c8a0 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a uccessful..**.**
3c8b0 20 7b 48 31 36 33 35 34 7d 20 41 20 6e 65 67 61 {H16354} A nega
3c8c0 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c tive or zero val
3c8d0 75 65 20 66 6f 72 20 4e 20 69 6e 20 61 20 63 61 ue for N in a ca
3c8e0 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ll to.**
3c8f0 20 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f [sqlite3_soft_
3c900 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d heap_limit(N)] m
3c910 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 eans that there
3c920 69 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 is no soft.**
3c930 20 20 20 20 20 20 20 68 65 61 70 20 6c 69 6d 69 heap limi
3c940 74 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 t and [sqlite3_r
3c950 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d elease_memory()]
3c960 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a will only be.**
3c970 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64 called
3c980 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 when memory is
3c990 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78 68 61 75 completely exhau
3c9a0 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 sted..**.** {H16
3c9b0 33 35 35 7d 20 54 68 65 20 64 65 66 61 75 6c 74 355} The default
3c9c0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 value for the s
3c9d0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
3c9e0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 s zero..**.** {H
3c9f0 31 36 33 35 38 7d 20 45 61 63 68 20 63 61 6c 6c 16358} Each call
3ca00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 to [sqlite3_sof
3ca10 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d t_heap_limit(N)]
3ca20 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a overrides the.*
3ca30 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
3ca40 73 20 73 65 74 20 62 79 20 61 6c 6c 20 70 72 69 s set by all pri
3ca50 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 or calls..*/.voi
3ca60 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 d sqlite3_soft_h
3ca70 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a eap_limit(int);.
3ca80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3ca90 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 Extract Metadat
3caa0 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e a About A Column
3cab0 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31 32 Of A Table {H12
3cac0 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2a 850} <S60300>.**
3cad0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
3cae0 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 returns metadat
3caf0 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 a about a specif
3cb00 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 ic column of a s
3cb10 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 pecific.** datab
3cb20 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 ase table access
3cb30 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b ible using the [
3cb40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3cb50 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 ion] handle.** p
3cb60 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
3cb70 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 st function argu
3cb80 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
3cb90 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 column is identi
3cba0 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f fied by the seco
3cbb0 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f nd, third and fo
3cbc0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 urth parameters
3cbd0 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 to.** this funct
3cbe0 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 ion. The second
3cbf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 parameter is eit
3cc00 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 her the name of
3cc10 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
3cc20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 (i.e. "main", "t
3cc30 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 emp" or an attac
3cc40 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f hed database) co
3cc50 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 ntaining the spe
3cc60 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 cified.** table
3cc70 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 or NULL. If it i
3cc80 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c s NULL, then all
3cc90 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
3cca0 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 ses are searched
3ccb0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c .** for the tabl
3ccc0 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
3ccd0 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 algorithm used
3cce0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 by the database
3ccf0 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 engine to.** res
3cd00 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 olve unqualified
3cd10 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 table reference
3cd20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 s..**.** The thi
3cd30 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 rd and fourth pa
3cd40 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 rameters to this
3cd50 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 function are th
3cd60 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 e table and colu
3cd70 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 mn.** name of th
3cd80 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e e desired column
3cd90 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 , respectively.
3cda0 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 Neither of these
3cdb0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d parameters.** m
3cdc0 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ay be NULL..**.*
3cdd0 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 * Metadata is re
3cde0 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e turned by writin
3cdf0 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 g to the memory
3ce00 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 locations passed
3ce10 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 as the 5th.** a
3ce20 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 nd subsequent pa
3ce30 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 rameters to this
3ce40 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f function. Any o
3ce50 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 f these argument
3ce60 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c s may be.** NULL
3ce70 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 , in which case
3ce80 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3ce90 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 g element of met
3cea0 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 adata is omitted
3ceb0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 ..**.** <blockqu
3cec0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
3ced0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
3cee0 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 r><th> Parameter
3cef0 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e <th> Output<br>
3cf00 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 Type <th> Descr
3cf10 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 iption.**.** <tr
3cf20 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 ><td> 5th <td> c
3cf30 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 onst char* <td>
3cf40 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 Data type.** <tr
3cf50 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 ><td> 6th <td> c
3cf60 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 onst char* <td>
3cf70 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 Name of default
3cf80 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
3cf90 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 ce.** <tr><td> 7
3cfa0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 th <td> int
3cfb0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 <td> True if
3cfc0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f column has a NO
3cfd0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e T NULL constrain
3cfe0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 t.** <tr><td> 8t
3cff0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 h <td> int
3d000 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 <td> True if
3d010 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f column is part o
3d020 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 f the PRIMARY KE
3d030 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 Y.** <tr><td> 9t
3d040 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 h <td> int
3d050 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 <td> True if
3d060 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 column is [AUTOI
3d070 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 NCREMENT].** </t
3d080 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
3d090 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
3d0a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 memory pointed
3d0b0 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 to by the charac
3d0c0 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 ter pointers ret
3d0d0 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a urned for the.**
3d0e0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 declaration typ
3d0f0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 e and collation
3d100 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 sequence is vali
3d110 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 d only until the
3d120 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f next.** call to
3d130 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 any SQLite API
3d140 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
3d150 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 If the specified
3d160 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c table is actual
3d170 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 ly a view, an [e
3d180 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
3d190 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 turned..**.** If
3d1a0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 the specified c
3d1b0 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 olumn is "rowid"
3d1c0 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 , "oid" or "_row
3d1d0 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b id_" and an.** [
3d1e0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
3d1f0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 KEY] column has
3d200 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 been explicitly
3d210 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 declared, then t
3d220 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 he output.** par
3d230 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 ameters are set
3d240 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 for the explicit
3d250 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 ly declared colu
3d260 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 mn. If there is
3d270 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 no.** explicitly
3d280 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 declared [INTEG
3d290 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 ER PRIMARY KEY]
3d2a0 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 column, then the
3d2b0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d output.** param
3d2c0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 eters are set as
3d2d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
3d2e0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 <pre>.** dat
3d2f0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 a type: "INTEGER
3d300 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 ".** collati
3d310 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 on sequence: "BI
3d320 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 NARY".** not
3d330 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 null: 0.**
3d340 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a primary key: 1.*
3d350 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 * auto incre
3d360 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 ment: 0.** </pre
3d370 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
3d380 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f ction may load o
3d390 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d ne or more schem
3d3a0 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 as from database
3d3b0 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a files. If an.**
3d3c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
3d3d0 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 ring this proces
3d3e0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 s, or if the req
3d3f0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 uested table or
3d400 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 column.** cannot
3d410 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 be found, an [e
3d420 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
3d430 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 turned and an er
3d440 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 ror message left
3d450 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 .** in the [data
3d460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3d470 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 (to be retrieve
3d480 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f d using sqlite3_
3d490 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a errmsg())..**.**
3d4a0 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c This API is onl
3d4b0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 y available if t
3d4c0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
3d4d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
3d4e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
3d4f0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
3d500 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 TA] C-preprocess
3d510 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 or symbol define
3d520 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
3d530 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 3_table_column_m
3d540 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 etadata(. sqlit
3d550 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
3d560 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 /* Connec
3d570 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 tion handle */.
3d580 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
3d590 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 Name, /*
3d5a0 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 Database name or
3d5b0 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 NULL */. const
3d5c0 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d char *zTableNam
3d5d0 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 e, /* Table
3d5e0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 name */. const
3d5f0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d char *zColumnNam
3d600 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 e, /* Column
3d610 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 name */. char c
3d620 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 onst **pzDataTyp
3d630 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a e, /* OUTPUT:
3d640 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 Declared data t
3d650 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f ype */. char co
3d660 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c nst **pzCollSeq,
3d670 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 /* OUTPUT:
3d680 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e Collation sequen
3d690 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 ce name */. int
3d6a0 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 *pNotNull,
3d6b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 /* OUTP
3d6c0 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 UT: True if NOT
3d6d0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 NULL constraint
3d6e0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 exists */. int
3d6f0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 *pPrimaryKey,
3d700 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 /* OUTPU
3d710 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d T: True if colum
3d720 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a n part of PK */.
3d730 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 int *pAutoinc
3d740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3d750 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 OUTPUT: True if
3d760 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d column is auto-
3d770 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a increment */.);.
3d780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3d790 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 Load An Extensi
3d7a0 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 30 on {H12600} <S20
3d7b0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 500>.**.** This
3d7c0 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 interface loads
3d7d0 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 an SQLite extens
3d7e0 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d ion library from
3d7f0 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e the named file.
3d800 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20 .**.** {H12601}
3d810 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 The sqlite3_load
3d820 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 _extension() int
3d830 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
3d840 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20 to load an.**
3d850 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 78 SQLite ex
3d860 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 tension library
3d870 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 contained in the
3d880 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a file zFile..**.
3d890 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 20 ** {H12602} The
3d8a0 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a entry point is z
3d8b0 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 Proc..**.** {H12
3d8c0 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 603} zProc may b
3d8d0 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 e 0, in which ca
3d8e0 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 se the name of t
3d8f0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a he entry point.*
3d900 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 * defau
3d910 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f lts to "sqlite3_
3d920 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e extension_init".
3d930 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20 .**.** {H12604}
3d940 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 The sqlite3_load
3d950 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 _extension() int
3d960 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 erface shall ret
3d970 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
3d980 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
3d990 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 uccess and [SQLI
3d9a0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d TE_ERROR] if som
3d9b0 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ething goes wron
3d9c0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35 g..**.** {H12605
3d9d0 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 } If an error oc
3d9e0 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 curs and pzErrMs
3d9f0 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e g is not 0, then
3da00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
3da10 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 [sqlite3_load_e
3da20 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 xtension()] inte
3da30 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 rface shall atte
3da40 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 mpt to.**
3da50 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 fill *pzErrMs
3da60 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 g with error mes
3da70 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 sage text stored
3da80 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 in memory.**
3da90 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 obtained
3daa0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
3dab0 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 lloc()]. {END}
3dac0 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 The calling func
3dad0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
3dae0 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 should free thi
3daf0 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c s memory by call
3db00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
3db10 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 e()]..**.** {H12
3db20 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 606} Extension l
3db30 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 oading must be e
3db40 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 nabled using.**
3db50 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3db60 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
3db70 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 tension()] prior
3db80 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 to calling this
3db90 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20 API,.**
3dba0 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 otherwise an e
3dbb0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 rror will be ret
3dbc0 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 urned..*/.int sq
3dbd0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
3dbe0 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 sion(. sqlite3
3dbf0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a *db, /*
3dc00 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 Load the extens
3dc10 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 ion into this da
3dc20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3dc30 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 n */. const cha
3dc40 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 r *zFile, /*
3dc50 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 Name of the shar
3dc60 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 ed library conta
3dc70 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 ining extension
3dc80 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
3dc90 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e *zProc, /* En
3dca0 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 try point. Deri
3dcb0 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 ved from zFile i
3dcc0 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a f 0 */. char **
3dcd0 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f pzErrMsg /
3dce0 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 * Put error mess
3dcf0 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 age here if not
3dd00 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 0 */.);../*.** C
3dd10 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 API3REF: Enable
3dd20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e Or Disable Exten
3dd30 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 sion Loading {H1
3dd40 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2620} <S20500>.*
3dd50 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 *.** So as not t
3dd60 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 o open security
3dd70 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 holes in older a
3dd80 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
3dd90 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 are.** unprepar
3dda0 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 ed to deal with
3ddb0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e extension loadin
3ddc0 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e g, and as a mean
3ddd0 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a s of disabling.*
3dde0 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 * extension load
3ddf0 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 ing while evalua
3de00 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 ting user-entere
3de10 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f d SQL, the follo
3de20 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 wing API.** is p
3de30 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 rovided to turn
3de40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 the [sqlite3_loa
3de50 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d d_extension()] m
3de60 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 echanism on and
3de70 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e off..**.** Exten
3de80 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 sion loading is
3de90 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 off by default.
3dea0 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 See ticket #1863
3deb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 7d ..**.** {H12621}
3dec0 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 Call the sqlite
3ded0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
3dee0 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e tension() routin
3def0 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a e with onoff==1.
3df00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 ** to t
3df10 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f urn extension lo
3df20 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c ading on and cal
3df30 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d l it with onoff=
3df40 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 20 =0 to turn.**
3df50 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20 6f it back o
3df60 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 ff again..**.**
3df70 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73 69 {H12622} Extensi
3df80 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 on loading is of
3df90 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f f by default..*/
3dfa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 .int sqlite3_ena
3dfb0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
3dfc0 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 on(sqlite3 *db,
3dfd0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a int onoff);../*.
3dfe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
3dff0 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 omatically Load
3e000 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b 48 An Extensions {H
3e010 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e 0a 12640} <S20500>.
3e020 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 **.** This API c
3e030 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 an be invoked at
3e040 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 program startup
3e050 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 in order to reg
3e060 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 ister.** one or
3e070 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 more statically
3e080 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e linked extension
3e090 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 s that will be a
3e0a0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 vailable.** to a
3e0b0 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 ll new [database
3e0c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b connections]. {
3e0d0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 END}.**.** This
3e0e0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 routine stores a
3e0f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
3e100 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 extension in an
3e110 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a 2a array that is.**
3e120 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
3e130 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
3e140 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20 61 ]. If you run a
3e150 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65 memory leak che
3e160 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20 cker.** on your
3e170 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 program and it r
3e180 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 eports a leak be
3e190 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61 72 cause of this ar
3e1a0 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b ray, invoke.** [
3e1b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 sqlite3_reset_au
3e1c0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 to_extension()]
3e1d0 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f 77 prior to shutdow
3e1e0 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 n to free the me
3e1f0 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 mory..**.** {H12
3e200 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 641} This functi
3e210 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 on registers an
3e220 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 extension entry
3e230 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a point that is.**
3e240 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 automa
3e250 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 tically invoked
3e260 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b whenever a new [
3e270 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3e280 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ion].**
3e290 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 is opened using
3e2a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
3e2b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
3e2c0 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 16()],.**
3e2d0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f or [sqlite3_o
3e2e0 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a pen_v2()]..**.**
3e2f0 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69 63 {H12642} Duplic
3e300 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 ate extensions a
3e310 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 re detected so c
3e320 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 alling this rout
3e330 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ine.**
3e340 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 multiple times w
3e350 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 ith the same ext
3e360 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 ension is harmle
3e370 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 ss..**.** {H1264
3e380 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 3} This routine
3e390 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 stores a pointer
3e3a0 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f to the extensio
3e3b0 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a n in an array.**
3e3c0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 that i
3e3d0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
3e3e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
3e3f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 )]..**.** {H1264
3e400 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 4} Automatic ext
3e410 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 ensions apply ac
3e420 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 ross all threads
3e430 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
3e440 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 _auto_extension(
3e450 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 void (*xEntryPoi
3e460 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a nt)(void));../*.
3e470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
3e480 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 et Automatic Ext
3e490 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b ension Loading {
3e4a0 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30 3e H12660} <S20500>
3e4b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
3e4c0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c tion disables al
3e4d0 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 l previously reg
3e4e0 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 istered automati
3e4f0 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e c.** extensions.
3e500 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f 65 {END} It undoe
3e510 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 s the effect of
3e520 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 all prior.** [sq
3e530 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e lite3_auto_exten
3e540 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a 2a sion()] calls..*
3e550 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 68 *.** {H12661} Th
3e560 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 is function disa
3e570 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 bles all previou
3e580 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a sly registered.*
3e590 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d * autom
3e5a0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e atic extensions.
3e5b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d 20 .**.** {H12662}
3e5c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 This function di
3e5d0 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 sables automatic
3e5e0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 extensions in a
3e5f0 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 ll threads..*/.v
3e600 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 oid sqlite3_rese
3e610 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e t_auto_extension
3e620 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a (void);../*.****
3e630 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 ** EXPERIMENTAL
3e640 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 - subject to cha
3e650 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 nge without noti
3e660 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ce *************
3e670 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 *.**.** The inte
3e680 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 rface to the vir
3e690 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
3e6a0 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c nism is currentl
3e6b0 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 y considered.**
3e6c0 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 to be experiment
3e6d0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 al. The interfa
3e6e0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 ce might change
3e6f0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 in incompatible
3e700 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ways..** If this
3e710 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f is a problem fo
3e720 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 r you, do not us
3e730 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 e the interface
3e740 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a at this time..**
3e750 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 .** When the vir
3e760 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
3e770 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c nism stabilizes,
3e780 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 we will declare
3e790 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 the.** interfac
3e7a0 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 e fixed, support
3e7b0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 it indefinitely
3e7c0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 , and remove thi
3e7d0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f s comment..*/../
3e7e0 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 *.** Structures
3e7f0 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 used by the virt
3e800 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 ual table interf
3e810 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ace.*/.typedef s
3e820 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
3e830 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b ab sqlite3_vtab;
3e840 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
3e850 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
3e860 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 fo sqlite3_index
3e870 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 _info;.typedef s
3e880 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
3e890 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 ab_cursor sqlite
3e8a0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 3_vtab_cursor;.t
3e8b0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
3e8c0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c lite3_module sql
3e8d0 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a ite3_module;../*
3e8e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
3e8f0 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 rtual Table Obje
3e900 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 30 ct {H18000} <S20
3e910 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 400>.** KEYWORDS
3e920 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 : sqlite3_module
3e930 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
3e940 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 .**.** A module
3e950 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 is a class of vi
3e960 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 rtual tables. E
3e970 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 ach module is de
3e980 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 fined.** by an i
3e990 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 nstance of the f
3e9a0 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 ollowing structu
3e9b0 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 re. This struct
3e9c0 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 ure consists.**
3e9d0 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 mostly of method
3e9e0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 s for the module
3e9f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
3ea00 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 erface is experi
3ea10 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 mental and is su
3ea20 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
3ea30 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e or.** removal in
3ea40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
3ea50 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 of SQLite..*/.s
3ea60 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f truct sqlite3_mo
3ea70 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 dule {. int iVe
3ea80 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 rsion;. int (*x
3ea90 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a Create)(sqlite3*
3eaa0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 , void *pAux,.
3eab0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
3eac0 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 argc, const cha
3ead0 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 r *const*argv,.
3eae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 sq
3eaf0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 lite3_vtab **ppV
3eb00 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 Tab, char**);.
3eb10 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 int (*xConnect)(
3eb20 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a sqlite3*, void *
3eb30 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 pAux,.
3eb40 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 int argc, c
3eb50 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 onst char *const
3eb60 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 *argv,.
3eb70 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 sqlite3_vt
3eb80 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 ab **ppVTab, cha
3eb90 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 r**);. int (*xB
3eba0 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 estIndex)(sqlite
3ebb0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 3_vtab *pVTab, s
3ebc0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
3ebd0 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 o*);. int (*xDi
3ebe0 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 sconnect)(sqlite
3ebf0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
3ec00 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 int (*xDestroy
3ec10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
3ec20 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
3ec30 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
3ec40 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 tab *pVTab, sqli
3ec50 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
3ec60 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 **ppCursor);. i
3ec70 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
3ec80 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
3ec90 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c *);. int (*xFil
3eca0 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ter)(sqlite3_vta
3ecb0 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 b_cursor*, int i
3ecc0 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 dxNum, const cha
3ecd0 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 r *idxStr,.
3ece0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
3ecf0 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c rgc, sqlite3_val
3ed00 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e ue **argv);. in
3ed10 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 t (*xNext)(sqlit
3ed20 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 e3_vtab_cursor*)
3ed30 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 ;. int (*xEof)(
3ed40 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
3ed50 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
3ed60 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f Column)(sqlite3_
3ed70 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 vtab_cursor*, sq
3ed80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
3ed90 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 int);. int (*xR
3eda0 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 owid)(sqlite3_vt
3edb0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 ab_cursor*, sqli
3edc0 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 te3_int64 *pRowi
3edd0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 d);. int (*xUpd
3ede0 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ate)(sqlite3_vta
3edf0 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 b *, int, sqlite
3ee00 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 3_value **, sqli
3ee10 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 te3_int64 *);.
3ee20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 int (*xBegin)(sq
3ee30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
3ee40 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e b);. int (*xSyn
3ee50 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 c)(sqlite3_vtab
3ee60 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
3ee70 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 *xCommit)(sqlite
3ee80 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
3ee90 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 int (*xRollbac
3eea0 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 k)(sqlite3_vtab
3eeb0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
3eec0 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 *xFindFunction)(
3eed0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
3eee0 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 tab, int nArg, c
3eef0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
3ef00 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
3ef10 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a void (*
3ef20 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 *pxFunc)(sqlite3
3ef30 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
3ef40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
3ef50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ef60 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 void **pp
3ef70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 Arg);. int (*xR
3ef80 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 ename)(sqlite3_v
3ef90 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 tab *pVtab, cons
3efa0 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d t char *zNew);.}
3efb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3efc0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 F: Virtual Table
3efd0 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d Indexing Inform
3efe0 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20 3c ation {H18100} <
3eff0 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20400>.** KEYWO
3f000 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 RDS: sqlite3_ind
3f010 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 ex_info.** EXPER
3f020 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
3f030 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f e sqlite3_index_
3f040 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 info structure a
3f050 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 nd its substruct
3f060 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a ures is used to.
3f070 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 ** pass informat
3f080 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 ion into and rec
3f090 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 eive the reply f
3f0a0 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 rom the xBestInd
3f0b0 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 ex.** method of
3f0c0 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c an sqlite3_modul
3f0d0 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 e. The fields u
3f0e0 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 nder **Inputs**
3f0f0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 are the.** input
3f100 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 s to xBestIndex
3f110 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c and are read-onl
3f120 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 y. xBestIndex i
3f130 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 nserts its.** re
3f140 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a sults into the *
3f150 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 *Outputs** field
3f160 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f s..**.** The aCo
3f170 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 nstraint[] array
3f180 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 records WHERE c
3f190 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 lause constraint
3f1a0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a s of the form:.*
3f1b0 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e *.** <pre>column
3f1c0 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a OP expr</pre>.*
3f1d0 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 *.** where OP is
3f1e0 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c =, <, <=,
3f1f0 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e >, or >=.
3f200 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 The particular
3f210 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 operator is.**
3f220 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 stored in aConst
3f230 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 raint[].op. The
3f240 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f index of the co
3f250 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 lumn is stored i
3f260 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 n.** aConstraint
3f270 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f [].iColumn. aCo
3f280 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c nstraint[].usabl
3f290 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 e is TRUE if the
3f2a0 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 .** expr on the
3f2b0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 right-hand side
3f2c0 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 can be evaluated
3f2d0 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 (and thus the c
3f2e0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 onstraint.** is
3f2f0 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 usable) and fals
3f300 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a e if it cannot..
3f310 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 **.** The optimi
3f320 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c zer automaticall
3f330 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 y inverts terms
3f340 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 of the form "exp
3f350 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 r OP column".**
3f360 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 and makes other
3f370 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 simplifications
3f380 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 to the WHERE cla
3f390 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 use in an attemp
3f3a0 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d t to.** get as m
3f3b0 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 any WHERE clause
3f3c0 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 terms into the
3f3d0 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 form shown above
3f3e0 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a as possible..**
3f3f0 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 The aConstraint
3f400 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 [] array only re
3f410 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 ports WHERE clau
3f420 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 se terms in the
3f430 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 correct.** form
3f440 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 that refer to th
3f450 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 e particular vir
3f460 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 tual table being
3f470 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 queried..**.**
3f480 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 Information abou
3f490 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 t the ORDER BY c
3f4a0 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 lause is stored
3f4b0 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a in aOrderBy[]..*
3f4c0 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 * Each term of a
3f4d0 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 OrderBy records
3f4e0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 a column of the
3f4f0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e ORDER BY clause.
3f500 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 .**.** The xBest
3f510 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 Index method mus
3f520 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 t fill aConstrai
3f530 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 ntUsage[] with i
3f540 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 nformation.** ab
3f550 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 out what paramet
3f560 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 ers to pass to x
3f570 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 Filter. If argv
3f580 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 Index>0 then.**
3f590 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 the right-hand s
3f5a0 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 ide of the corre
3f5b0 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 sponding aConstr
3f5c0 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 aint[] is evalua
3f5d0 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d ted.** and becom
3f5e0 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 es the argvIndex
3f5f0 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 -th entry in arg
3f600 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 v. If aConstrai
3f610 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a ntUsage[].omit.*
3f620 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 * is true, then
3f630 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 the constraint i
3f640 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 s assumed to be
3f650 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 fully handled by
3f660 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 the.** virtual
3f670 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 table and is not
3f680 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 checked again b
3f690 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 y SQLite..**.**
3f6a0 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 The idxNum and i
3f6b0 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 dxPtr values are
3f6c0 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 recorded and pa
3f6d0 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 ssed into xFilte
3f6e0 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 r..** sqlite3_fr
3f6f0 65 65 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 ee() is used to
3f700 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 6e free idxPtr if n
3f710 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 eedToFreeIdxPtr
3f720 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 is true..**.** T
3f730 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d he orderByConsum
3f740 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 ed means that ou
3f750 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 tput from xFilte
3f760 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a r will occur in.
3f770 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f ** the correct o
3f780 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 rder to satisfy
3f790 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
3f7a0 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 use so that no s
3f7b0 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 eparate.** sorti
3f7c0 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 ng step is requi
3f7d0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 red..**.** The e
3f7e0 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c stimatedCost val
3f7f0 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 ue is an estimat
3f800 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 e of the cost of
3f810 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 doing the.** pa
3f820 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e rticular lookup.
3f830 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 A full scan of
3f840 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 a table with N
3f850 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 entries should h
3f860 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 ave.** a cost of
3f870 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 N. A binary se
3f880 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 arch of a table
3f890 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f of N entries sho
3f8a0 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f uld have a.** co
3f8b0 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 st of approximat
3f8c0 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2a 0a 2a ely log(N)..**.*
3f8d0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
3f8e0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
3f8f0 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
3f900 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
3f910 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
3f920 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
3f930 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 Lite..*/.struct
3f940 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
3f950 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 fo {. /* Inputs
3f960 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 */. int nConst
3f970 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 raint;
3f980 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e /* Number of en
3f990 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 tries in aConstr
3f9a0 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 aint */. struct
3f9b0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
3f9c0 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 onstraint {.
3f9d0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
3f9e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
3f9f0 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e lumn on left-han
3fa00 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 d side of constr
3fa10 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 aint */. uns
3fa20 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 igned char op;
3fa30 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 /* Constr
3fa40 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f aint operator */
3fa50 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
3fa60 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 har usable;
3fa70 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 /* True if this
3fa80 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 constraint is us
3fa90 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 able */. int
3faa0 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 iTermOffset;
3fab0 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
3fac0 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 nternally - xBes
3fad0 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 tIndex should ig
3fae0 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f nore */. } *aCo
3faf0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
3fb00 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 /* Table of
3fb10 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
3fb20 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 nstraints */. i
3fb30 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 nt nOrderBy;
3fb40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
3fb50 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
3fb60 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
3fb70 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 use */. struct
3fb80 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 sqlite3_index_or
3fb90 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 derby {. int
3fba0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 iColumn;
3fbb0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e /* Column
3fbc0 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 number */.
3fbd0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 unsigned char de
3fbe0 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 sc; /* Tru
3fbf0 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c e for DESC. Fal
3fc00 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 se for ASC. */.
3fc10 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 } *aOrderBy;
3fc20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 /* T
3fc30 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
3fc40 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 se */. /* Outpu
3fc50 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 ts */. struct s
3fc60 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
3fc70 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a straint_usage {.
3fc80 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 int argvInde
3fc90 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 x; /*
3fca0 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e if >0, constrain
3fcb0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 t is part of arg
3fcc0 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a v to xFilter */.
3fcd0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
3fce0 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 r omit; /*
3fcf0 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 Do not code a te
3fd00 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 st for this cons
3fd10 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 traint */. } *a
3fd20 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b ConstraintUsage;
3fd30 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 . int idxNum;
3fd40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3fd50 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 Number used to
3fd60 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 identify the ind
3fd70 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 ex */. char *id
3fd80 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 xStr;
3fd90 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f /* String, po
3fda0 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 ssibly obtained
3fdb0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
3fdc0 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 loc */. int nee
3fdd0 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 dToFreeIdxStr;
3fde0 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 /* Free idxS
3fdf0 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 tr using sqlite3
3fe00 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 _free() if true
3fe10 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 */. int orderBy
3fe20 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 Consumed;
3fe30 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 /* True if outpu
3fe40 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 t is already ord
3fe50 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 ered */. double
3fe60 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 estimatedCost;
3fe70 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 /* Estimate
3fe80 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 d cost of using
3fe90 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b this index */.};
3fea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3feb0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3fec0 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 _EQ 2.#define
3fed0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
3fee0 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 NSTRAINT_GT 4
3fef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3ff00 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3ff10 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 _LE 8.#define
3ff20 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
3ff30 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 NSTRAINT_LT 1
3ff40 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
3ff50 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
3ff60 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 T_GE 32.#defi
3ff70 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
3ff80 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 CONSTRAINT_MATCH
3ff90 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 64../*.** CAPI3
3ffa0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
3ffb0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d Virtual Table Im
3ffc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 plementation {H1
3ffd0 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8200} <S20400>.*
3ffe0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3fff0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
40000 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 e is used to reg
40010 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64 75 ister a new modu
40020 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 0a 2a le name with a.*
40030 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
40040 65 63 74 69 6f 6e 5d 2e 20 20 4d 6f 64 75 6c 65 ection]. Module
40050 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 names must be r
40060 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 egistered before
40070 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 6e 65 77 .** creating new
40080 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
40090 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f on the module, o
400a0 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 0a 2a r before using.*
400b0 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 * preexisting vi
400c0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 66 20 rtual tables of
400d0 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a the module..**.*
400e0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
400f0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
40100 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
40110 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
40120 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
40130 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
40140 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
40150 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
40160 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
40170 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 module(. sqlite
40180 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
40190 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 /* SQLite c
401a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 onnection to reg
401b0 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 ister module wit
401c0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 h */. const cha
401d0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 r *zName,
401e0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
401f0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e module */. con
40200 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c st sqlite3_modul
40210 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f e *, /* Metho
40220 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
40230 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20 e */. void *
40240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40250 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 /* Client data
40260 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f for xCreate/xCo
40270 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a nnect */.);../*.
40280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
40290 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 ister A Virtual
402a0 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 Table Implementa
402b0 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53 tion {H18210} <S
402c0 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20400>.** EXPERI
402d0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 MENTAL.**.** Thi
402e0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 s routine is ide
402f0 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73 ntical to the [s
40300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
40310 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 20 61 dule()] method a
40320 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 bove,.** except
40330 74 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 that it allows a
40340 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 destructor func
40350 74 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 tion to be speci
40360 66 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 fied. It is.** e
40370 76 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d ven more experim
40380 65 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 ental than the r
40390 65 73 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 est of the virtu
403a0 61 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a al tables API..*
403b0 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d /.SQLITE_EXPERIM
403c0 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
403d0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 3_create_module_
403e0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
403f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
40400 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 /* SQLite conne
40410 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 ction to registe
40420 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f r module with */
40430 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
40440 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a Name, /*
40450 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 Name of the mod
40460 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 ule */. const s
40470 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c qlite3_module *,
40480 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 /* Methods f
40490 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f or the module */
404a0 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
404b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
404c0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 Client data for
404d0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 xCreate/xConnec
404e0 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 t */. void(*xDe
404f0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 stroy)(void*)
40500 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 /* Module dest
40510 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 ructor function
40520 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
40530 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
40540 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 able Instance Ob
40550 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 ject {H18010} <S
40560 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 20400>.** KEYWOR
40570 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 DS: sqlite3_vtab
40580 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
40590 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 .**.** Every mod
405a0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
405b0 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 on uses a subcla
405c0 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ss of the follow
405d0 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a ing structure.**
405e0 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 to describe a p
405f0 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e articular instan
40600 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 ce of the module
40610 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 . Each subclass
40620 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c will.** be tail
40630 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 ored to the spec
40640 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 ific needs of th
40650 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 e module impleme
40660 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 ntation..** The
40670 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 purpose of this
40680 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f superclass is to
40690 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 define certain
406a0 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a fields that are.
406b0 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c ** common to all
406c0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e module implemen
406d0 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 tations..**.** V
406e0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 irtual tables me
406f0 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e thods can set an
40700 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 error message b
40710 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a y assigning a.**
40720 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
40730 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
40740 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 printf()] to zEr
40750 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f rMsg. The metho
40760 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 d should.** take
40770 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 care that any p
40780 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 rior string is f
40790 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 reed by a call t
407a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
407b0 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 )].** prior to a
407c0 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 ssigning a new s
407d0 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 tring to zErrMsg
407e0 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72 . After the err
407f0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 or message.** is
40800 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f delivered up to
40810 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c the client appl
40820 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 ication, the str
40830 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ing will be auto
40840 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 matically.** fre
40850 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 ed by sqlite3_fr
40860 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 ee() and the zEr
40870 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 rMsg field will
40880 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 be zeroed. Note
40890 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 .** that sqlite3
408a0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
408b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 qlite3_free() ar
408c0 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 e used on the zE
408d0 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 rrMsg field.** s
408e0 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 ince virtual tab
408f0 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 les are commonly
40900 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 implemented in
40910 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 loadable extensi
40920 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 ons which.** do
40930 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 20 not have access
40940 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 to sqlite3MPrint
40950 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 f() or sqlite3Fr
40960 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ee()..**.** This
40970 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 interface is ex
40980 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
40990 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
409a0 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 nge or.** remova
409b0 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 l in future rele
409c0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
409d0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
409e0 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 3_vtab {. const
409f0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
40a00 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 *pModule; /* Th
40a10 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 e module for thi
40a20 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 s virtual table
40a30 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 */. int nRef;
40a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40a50 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 /* Used int
40a60 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 ernally */. cha
40a70 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 r *zErrMsg;
40a80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
40a90 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 Error message fr
40aa0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e om sqlite3_mprin
40ab0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 tf() */. /* Vir
40ac0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
40ad0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 mentations will
40ae0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 typically add ad
40af0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
40b00 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
40b10 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
40b20 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 able Cursor Obje
40b30 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 ct {H18020} <S2
40b40 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
40b50 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f S: sqlite3_vtab_
40b60 63 75 72 73 6f 72 0a 2a 2a 20 45 58 50 45 52 49 cursor.** EXPERI
40b70 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 MENTAL.**.** Eve
40b80 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d ry module implem
40b90 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 entation uses a
40ba0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 subclass of the
40bb0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 following struct
40bc0 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 ure.** to descri
40bd0 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 be cursors that
40be0 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 point into the v
40bf0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 irtual table and
40c00 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 are used.** to
40c10 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 loop through the
40c20 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 virtual table.
40c30 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 Cursors are cre
40c40 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ated using the.*
40c50 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f * xOpen method o
40c60 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 f the module. E
40c70 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 ach module imple
40c80 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 mentation will d
40c90 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e efine.** the con
40ca0 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 tent of a cursor
40cb0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 structure to su
40cc0 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 it its own needs
40cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 ..**.** This sup
40ce0 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 erclass exists i
40cf0 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e n order to defin
40d00 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 e fields of the
40d10 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 cursor that.** a
40d20 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c re common to all
40d30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
40d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
40d50 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 erface is experi
40d60 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 mental and is su
40d70 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
40d80 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e or.** removal in
40d90 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
40da0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 of SQLite..*/.s
40db0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
40dc0 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 ab_cursor {. sq
40dd0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
40de0 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 b; /* Virtu
40df0 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 al table of this
40e00 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 cursor */. /*
40e10 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d Virtual table im
40e20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 plementations wi
40e30 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 ll typically add
40e40 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
40e50 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 ds */.};../*.**
40e60 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
40e70 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 e The Schema Of
40e80 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 A Virtual Table
40e90 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30 30 {H18280} <S20400
40ea0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
40eb0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 L.**.** The xCre
40ec0 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 ate and xConnect
40ed0 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f methods of a mo
40ee0 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c dule use the fol
40ef0 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f lowing API.** to
40f00 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 declare the for
40f10 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 mat (the names a
40f20 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 nd datatypes of
40f30 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a the columns) of.
40f40 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 ** the virtual t
40f50 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 ables they imple
40f60 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ment..**.** This
40f70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 interface is ex
40f80 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
40f90 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
40fa0 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 nge or.** remova
40fb0 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 l in future rele
40fc0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
40fd0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
40fe0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
40ff0 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 e3_declare_vtab(
41000 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 sqlite3*, const
41010 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 char *zCreateTab
41020 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 le);../*.** CAPI
41030 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 3REF: Overload A
41040 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 Function For A
41050 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 Virtual Table {H
41060 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18300} <S20400>.
41070 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
41080 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 **.** Virtual ta
41090 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 bles can provide
410a0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 alternative imp
410b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
410c0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 functions.** usi
410d0 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 ng the xFindFunc
410e0 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 tion method. Bu
410f0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e t global version
41100 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 s of those funct
41110 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 ions.** must exi
41120 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 st in order to b
41130 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a e overloaded..**
41140 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b .** This API mak
41150 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c es sure a global
41160 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 version of a fu
41170 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 nction with a pa
41180 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 rticular.** name
41190 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 and number of p
411a0 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 arameters exists
411b0 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 . If no such fu
411c0 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a nction exists.**
411d0 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 before this API
411e0 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 is called, a ne
411f0 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 w function is cr
41200 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c eated. The impl
41210 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
41220 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f the new functio
41230 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 n always causes
41240 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 an exception to
41250 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a be thrown. So.*
41260 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 * the new functi
41270 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 on is not good f
41280 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 or anything by i
41290 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 tself. Its only
412a0 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 .** purpose is t
412b0 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 o be a placehold
412c0 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 er function that
412d0 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 can be overload
412e0 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c ed.** by virtual
412f0 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 tables..**.** T
41300 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 his API should b
41310 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 e considered par
41320 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c t of the virtual
41330 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 table interface
41340 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 ,.** which is ex
41350 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 perimental and s
41360 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
41370 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 ..*/.SQLITE_EXPE
41380 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
41390 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 ite3_overload_fu
413a0 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c nction(sqlite3*,
413b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
413c0 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 ncName, int nArg
413d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e );../*.** The in
413e0 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 terface to the v
413f0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 irtual-table mec
41400 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 hanism defined a
41410 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a bove (back up.**
41420 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 to a comment re
41430 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 markably similar
41440 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 to this one) is
41450 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 currently consi
41460 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 dered.** to be e
41470 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 xperimental. Th
41480 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 e interface migh
41490 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f t change in inco
414a0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a mpatible ways..*
414b0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 * If this is a p
414c0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 roblem for you,
414d0 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 do not use the i
414e0 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 nterface at this
414f0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 time..**.** Whe
41500 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 n the virtual-ta
41510 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 ble mechanism st
41520 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c abilizes, we wil
41530 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a l declare the.**
41540 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 interface fixed
41550 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 , support it ind
41560 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 efinitely, and r
41570 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 emove this comme
41580 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 nt..**.****** EX
41590 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 PERIMENTAL - sub
415a0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 ject to change w
415b0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a ithout notice **
415c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a ************.*/.
415d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
415e0 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 A Handle To An
415f0 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 Open BLOB {H1780
41600 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 0} <S30230>.** K
41610 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 EYWORDS: {BLOB h
41620 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e andle} {BLOB han
41630 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 dles}.**.** An i
41640 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
41650 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
41660 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f s an open BLOB o
41670 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 n which.** [sqli
41680 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
41690 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
416a0 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 I/O] can be per
416b0 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 formed..** Objec
416c0 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 ts of this type
416d0 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b are created by [
416e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
416f0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 n()].** and dest
41700 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
41710 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
41720 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
41730 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e _blob_read()] an
41740 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f d [sqlite3_blob_
41750 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 write()] interfa
41760 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ces.** can be us
41770 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 ed to read or wr
41780 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 ite small subsec
41790 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f tions of the BLO
417a0 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 B..** The [sqlit
417b0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d e3_blob_bytes()]
417c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
417d0 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 ns the size of t
417e0 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 he BLOB in bytes
417f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
41800 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 uct sqlite3_blob
41810 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a sqlite3_blob;..
41820 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
41830 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 Open A BLOB For
41840 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 Incremental I/O
41850 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 {H17810} <S30230
41860 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 >.**.** This int
41870 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 erfaces opens a
41880 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 [BLOB handle | h
41890 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c andle] to the BL
418a0 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e OB located.** in
418b0 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d row iRow, colum
418c0 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 n zColumn, table
418d0 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 zTable in datab
418e0 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f ase zDb;.** in o
418f0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
41900 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 same BLOB that w
41910 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 ould be selected
41920 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e by:.**.** <pre>
41930 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a .** SELECT z
41940 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e Column FROM zDb.
41950 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f zTable WHERE [ro
41960 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 wid] = iRow;.**
41970 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a </pre> {END}.**.
41980 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 ** If the flags
41990 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e parameter is non
419a0 2d 7a 65 72 6f 2c 20 74 68 65 20 74 68 65 20 42 -zero, the the B
419b0 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f LOB is opened fo
419c0 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 r read.** and wr
419d0 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 ite access. If i
419e0 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 t is zero, the B
419f0 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f LOB is opened fo
41a00 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a r read access..*
41a10 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
41a20 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 he database name
41a30 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 is not the file
41a40 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 name that contai
41a50 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 ns.** the databa
41a60 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68 se but rather th
41a70 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 e symbolic name
41a80 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
41a90 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 that.** is assig
41aa0 6e 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 ned when the dat
41ab0 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 abase is connect
41ac0 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 ed using [ATTACH
41ad0 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 ]..** For the ma
41ae0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
41af0 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e , the database n
41b00 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a ame is "main"..*
41b10 2a 20 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 * For TEMP table
41b20 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 s, the database
41b30 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a name is "temp"..
41b40 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
41b50 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 , [SQLITE_OK] is
41b60 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 returned and th
41b70 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 e new [BLOB hand
41b80 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a le] is written.*
41b90 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 * to *ppBlob. Ot
41ba0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
41bb0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
41bc0 6e 65 64 20 61 6e 64 20 61 6e 79 20 76 61 6c 75 ned and any valu
41bd0 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 e written.** to
41be0 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e *ppBlob should n
41bf0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 ot be used by th
41c00 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 e caller..** Thi
41c10 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 s function sets
41c20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
41c30 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 nnection] error
41c40 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
41c50 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 .** accessible v
41c60 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 ia [sqlite3_errc
41c70 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ode()] and [sqli
41c80 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
41c90 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f 77 20 *.** If the row
41ca0 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 that a BLOB hand
41cb0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 le points to is
41cc0 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a modified by an.*
41cd0 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c * [UPDATE], [DEL
41ce0 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 ETE], or by [ON
41cf0 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 CONFLICT] side-e
41d00 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 ffects.** then t
41d10 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 he BLOB handle i
41d20 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 s marked as "exp
41d30 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 ired"..** This i
41d40 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f s true if any co
41d50 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 lumn of the row
41d60 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e is changed, even
41d70 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 a column.** oth
41d80 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 er than the one
41d90 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 the BLOB handle
41da0 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 is open on..** C
41db0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
41dc0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e _blob_read()] an
41dd0 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f d [sqlite3_blob_
41de0 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 write()] for.**
41df0 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 a expired BLOB h
41e00 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 andle fail with
41e10 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f an return code o
41e20 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d f [SQLITE_ABORT]
41e30 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 72 69 ..** Changes wri
41e40 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 tten into a BLOB
41e50 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c prior to the BL
41e60 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 OB expiring are
41e70 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 not.** rollback
41e80 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f by the expiratio
41e90 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 n of the BLOB.
41ea0 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c Such changes wil
41eb0 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 l eventually.**
41ec0 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 commit if the tr
41ed0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e ansaction contin
41ee0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f ues to completio
41ef0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 n..**.** INVARIA
41f00 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 NTS:.**.** {H178
41f10 31 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 13} A successful
41f20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 invocation of t
41f30 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
41f40 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c _open(D,B,T,C,R,
41f50 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 F,P)].**
41f60 20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c interface shal
41f70 6c 20 6f 70 65 6e 20 61 6e 20 5b 73 71 6c 69 74 l open an [sqlit
41f80 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 e3_blob] object
41f90 50 20 6f 6e 20 74 68 65 20 42 4c 4f 42 0a 2a 2a P on the BLOB.**
41fa0 20 20 20 20 20 20 20 20 20 20 69 6e 20 63 6f 6c in col
41fb0 75 6d 6e 20 43 20 6f 66 20 74 68 65 20 74 61 62 umn C of the tab
41fc0 6c 65 20 54 20 69 6e 20 74 68 65 20 64 61 74 61 le T in the data
41fd0 62 61 73 65 20 42 20 6f 6e 0a 2a 2a 20 20 20 20 base B on.**
41fe0 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 the [datab
41ff0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
42000 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 31 34 D..**.** {H17814
42010 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 } A successful i
42020 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
42030 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
42040 44 2c 2e 2e 2e 29 5d 20 73 68 61 6c 6c 20 73 74 D,...)] shall st
42050 61 72 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 art.**
42060 61 20 6e 65 77 20 74 72 61 6e 73 61 63 74 69 6f a new transactio
42070 6e 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 n on the [databa
42080 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
42090 20 69 66 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 if that.**
420a0 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 connection
420b0 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 is not already i
420c0 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e n a transaction.
420d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 31 36 7d 20 .**.** {H17816}
420e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f The [sqlite3_blo
420f0 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 b_open(D,B,T,C,R
42100 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
42110 20 73 68 61 6c 6c 20 6f 70 65 6e 0a 2a 2a 20 20 shall open.**
42120 20 20 20 20 20 20 20 20 74 68 65 20 42 4c 4f 42 the BLOB
42130 20 66 6f 72 20 72 65 61 64 20 61 6e 64 20 77 72 for read and wr
42140 69 74 65 20 61 63 63 65 73 73 20 69 66 20 61 6e ite access if an
42150 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 46 0a d only if the F.
42160 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 ** para
42170 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 meter is non-zer
42180 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 31 39 o..**.** {H17819
42190 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 } The [sqlite3_b
421a0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 69 6e 74 65 lob_open()] inte
421b0 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 rface shall retu
421c0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
421d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 n.** su
421e0 63 63 65 73 73 20 61 6e 64 20 61 6e 20 61 70 70 ccess and an app
421f0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
42200 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 code] on failure
42210 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 32 31 7d ..**.** {H17821}
42220 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 If an error occ
42230 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 urs during evalu
42240 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
42250 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 3_blob_open(D,..
42260 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
42270 74 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 then subsequent
42280 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
42290 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 3_errcode(D)],.*
422a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
422b0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
422c0 63 6f 64 65 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 code()], .**
422d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 [sqlite3_e
422e0 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b rrmsg(D)], and [
422f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
42300 28 44 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 (D)] shall retur
42310 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e n.** in
42320 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 formation approp
42330 72 69 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 riate for that e
42340 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 rror..**.** {H17
42350 38 32 34 7d 20 49 66 20 61 6e 79 20 63 6f 6c 75 824} If any colu
42360 6d 6e 20 69 6e 20 74 68 65 20 72 6f 77 20 74 68 mn in the row th
42370 61 74 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 6c at a [sqlite3_bl
42380 6f 62 5d 20 68 61 73 20 6f 70 65 6e 20 69 73 0a ob] has open is.
42390 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 6e ** chan
423a0 67 65 64 20 62 79 20 61 20 73 65 70 61 72 61 74 ged by a separat
423b0 65 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 e [UPDATE] or [D
423c0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 ELETE] statement
423d0 20 6f 72 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 or by.**
423e0 20 20 20 61 6e 20 5b 4f 4e 20 43 4f 4e 46 4c 49 an [ON CONFLI
423f0 43 54 5d 20 73 69 64 65 20 65 66 66 65 63 74 2c CT] side effect,
42400 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
42410 65 33 5f 62 6c 6f 62 5d 20 73 68 61 6c 6c 0a 2a e3_blob] shall.*
42420 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 6d 61 * be ma
42430 72 6b 65 64 20 61 73 20 69 6e 76 61 6c 69 64 2e rked as invalid.
42440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
42450 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c blob_open(. sql
42460 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 ite3*,. const c
42470 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 har *zDb,. cons
42480 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a t char *zTable,.
42490 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
424a0 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 olumn,. sqlite3
424b0 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 _int64 iRow,. i
424c0 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 nt flags,. sqli
424d0 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f te3_blob **ppBlo
424e0 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 b.);../*.** CAPI
424f0 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 3REF: Close A BL
42500 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 OB Handle {H1783
42510 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 0} <S30230>.**.*
42520 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e * Closes an open
42530 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a [BLOB handle]..
42540 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 **.** Closing a
42550 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 BLOB shall cause
42560 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 the current tra
42570 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d nsaction to comm
42580 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 it.** if there a
42590 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 re no other BLOB
425a0 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 s, no pending pr
425b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
425c0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 s, and the.** da
425d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
425e0 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d n is in [autocom
425f0 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 mit mode]..** If
42600 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 any writes were
42610 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f made to the BLO
42620 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 B, they might be
42630 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a held in cache.*
42640 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 * until the clos
42650 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 e operation if t
42660 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45 hey will fit. {E
42670 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e ND}.**.** Closin
42680 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e g the BLOB often
42690 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e forces the chan
426a0 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 ges.** out to di
426b0 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 sk and so if any
426c0 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 I/O errors occu
426d0 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b r, they will lik
426e0 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 ely occur.** at
426f0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 the time when th
42700 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 e BLOB is closed
42710 2e 20 20 7b 48 31 37 38 33 33 7d 20 41 6e 79 20 . {H17833} Any
42720 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
42730 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 r during.** clos
42740 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 ing are reported
42750 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 as a non-zero r
42760 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a eturn value..**.
42770 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 ** The BLOB is c
42780 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f losed unconditio
42790 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 nally. Even if
427a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
427b0 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 urns.** an error
427c0 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 code, the BLOB
427d0 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e is still closed.
427e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
427f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 33 33 S:.**.** {H17833
42800 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 } The [sqlite3_b
42810 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69 6e lob_close(P)] in
42820 74 65 72 66 61 63 65 20 63 6c 6f 73 65 73 20 61 terface closes a
42830 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d n [sqlite3_blob]
42840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a .** obj
42850 65 63 74 20 50 20 70 72 65 76 69 6f 75 73 6c 79 ect P previously
42860 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 opened using [s
42870 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
42880 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 ()]..**.** {H178
42890 33 36 7d 20 43 6c 6f 73 69 6e 67 20 61 6e 20 5b 36} Closing an [
428a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 sqlite3_blob] ob
428b0 6a 65 63 74 20 75 73 69 6e 67 0a 2a 2a 20 20 20 ject using.**
428c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
428d0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 73 68 blob_close()] sh
428e0 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 all cause the cu
428f0 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f rrent transactio
42900 6e 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 n to.**
42910 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 72 65 commit if there
42920 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 6f 70 are no other op
42930 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 en [sqlite3_blob
42940 5d 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 20 20 20 ] objects.**
42950 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 or [prepar
42960 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f ed statements] o
42970 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 n the same [data
42980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
42990 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
429a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
429b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b nnection is in [
429c0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d autocommit mode]
429d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 33 39 7d ..**.** {H17839}
429e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c The [sqlite3_bl
429f0 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69 6e 74 ob_close(P)] int
42a00 65 72 66 61 63 65 73 20 73 68 61 6c 6c 20 63 6c erfaces shall cl
42a10 6f 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ose the.**
42a20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f [sqlite3_blo
42a30 62 5d 20 6f 62 6a 65 63 74 20 50 20 75 6e 63 6f b] object P unco
42a40 6e 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 76 65 nditionally, eve
42a50 6e 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 n if.**
42a60 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
42a70 6c 6f 73 65 28 50 29 5d 20 72 65 74 75 72 6e 73 lose(P)] returns
42a80 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
42a90 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
42aa0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
42ab0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 3_blob_close(sql
42ac0 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f ite3_blob *);../
42ad0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
42ae0 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f eturn The Size O
42af0 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b f An Open BLOB {
42b00 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e H17840} <S30230>
42b10 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 .**.** Returns t
42b20 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 he size in bytes
42b30 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 of the BLOB acc
42b40 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 essible via the
42b50 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20 68 open.** []BLOB h
42b60 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e andle] in its on
42b70 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a ly argument..**.
42b80 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
42b90 2a 0a 2a 2a 20 7b 48 31 37 38 34 33 7d 20 54 68 *.** {H17843} Th
42ba0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
42bb0 62 79 74 65 73 28 50 29 5d 20 69 6e 74 65 72 66 bytes(P)] interf
42bc0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
42bd0 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 size.**
42be0 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 in bytes of the
42bf0 20 42 4c 4f 42 20 74 68 61 74 20 74 68 65 20 5b BLOB that the [
42c00 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 sqlite3_blob] ob
42c10 6a 65 63 74 20 50 0a 2a 2a 20 20 20 20 20 20 20 ject P.**
42c20 20 20 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2f refers to..*/
42c30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
42c40 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f b_bytes(sqlite3_
42c50 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 blob *);../*.**
42c60 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 CAPI3REF: Read D
42c70 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 ata From A BLOB
42c80 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 Incrementally {H
42c90 31 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 17850} <S30230>.
42ca0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
42cb0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 ion is used to r
42cc0 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e ead data from an
42cd0 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
42ce0 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 le] into a.** ca
42cf0 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 ller-supplied bu
42d00 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 ffer. N bytes of
42d10 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
42d20 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a into buffer Z.*
42d30 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 * from the open
42d40 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 BLOB, starting a
42d50 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 t offset iOffset
42d60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 ..**.** If offse
42d70 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 t iOffset is les
42d80 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 s than N bytes f
42d90 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 rom the end of t
42da0 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c he BLOB,.** [SQL
42db0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 ITE_ERROR] is re
42dc0 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 turned and no da
42dd0 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 ta is read. If
42de0 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a N or iOffset is.
42df0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 ** less than zer
42e00 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 o, [SQLITE_ERROR
42e10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
42e20 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 d no data is rea
42e30 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 d..**.** An atte
42e40 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d mpt to read from
42e50 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f an expired [BLO
42e60 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 B handle] fails
42e70 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 with an.** error
42e80 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 code of [SQLITE
42e90 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f _ABORT]..**.** O
42ea0 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 n success, SQLIT
42eb0 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 E_OK is returned
42ec0 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 ..** Otherwise,
42ed0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
42ee0 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 or an [extended
42ef0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
42f00 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
42f10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
42f20 20 7b 48 31 37 38 35 33 7d 20 41 20 73 75 63 63 {H17853} A succ
42f30 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
42f40 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c n of [sqlite3_bl
42f50 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 ob_read(P,Z,N,X)
42f60 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 ] .** s
42f70 68 61 6c 6c 20 72 65 61 64 73 20 4e 20 62 79 74 hall reads N byt
42f80 65 73 20 6f 66 20 64 61 74 61 20 6f 75 74 20 6f es of data out o
42f90 66 20 74 68 65 20 42 4c 4f 42 20 72 65 66 65 72 f the BLOB refer
42fa0 65 6e 63 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 enced by.**
42fb0 20 20 20 20 20 5b 42 4c 4f 42 20 68 61 6e 64 6c [BLOB handl
42fc0 65 5d 20 50 20 62 65 67 69 6e 6e 69 6e 67 20 61 e] P beginning a
42fd0 74 20 6f 66 66 73 65 74 20 58 20 61 6e 64 20 73 t offset X and s
42fe0 74 6f 72 65 20 74 68 6f 73 65 20 62 79 74 65 73 tore those bytes
42ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
43000 6f 20 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a o buffer Z..**.*
43010 2a 20 7b 48 31 37 38 35 36 7d 20 49 6e 20 5b 73 * {H17856} In [s
43020 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
43030 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 74 68 (P,Z,N,X)] if th
43040 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c e size of the BL
43050 4f 42 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 OB.** i
43060 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 s less than N+X
43070 62 79 74 65 73 2c 20 74 68 65 6e 20 74 68 65 20 bytes, then the
43080 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6c function shall l
43090 65 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 eave the.**
430a0 20 20 20 20 20 5a 20 62 75 66 66 65 72 20 75 6e Z buffer un
430b0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 changed and retu
430c0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
430d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 35 39 ]..**.** {H17859
430e0 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c } In [sqlite3_bl
430f0 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 ob_read(P,Z,N,X)
43100 5d 20 69 66 20 58 20 6f 72 20 4e 20 69 73 20 6c ] if X or N is l
43110 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 0a 2a 2a ess than zero.**
43120 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 then t
43130 68 65 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c he function shal
43140 6c 20 6c 65 61 76 65 20 74 68 65 20 5a 20 62 75 l leave the Z bu
43150 66 66 65 72 20 75 6e 63 68 61 6e 67 65 64 0a 2a ffer unchanged.*
43160 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 72 * and r
43170 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
43180 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ROR]..**.** {H17
43190 38 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 862} The [sqlite
431a0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 3_blob_read(P,Z,
431b0 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 N,X)] interface
431c0 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 shall return [SQ
431d0 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 LITE_OK].**
431e0 20 20 20 20 20 69 66 20 4e 20 62 79 74 65 73 20 if N bytes
431f0 61 72 65 20 73 75 63 63 65 73 73 66 75 6c 6c 79 are successfully
43200 20 72 65 61 64 20 69 6e 74 6f 20 62 75 66 66 65 read into buffe
43210 72 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 r Z..**.** {H178
43220 36 33 7d 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 63} If the [BLOB
43230 20 68 61 6e 64 6c 65 5d 20 50 20 69 73 20 65 78 handle] P is ex
43240 70 69 72 65 64 20 61 6e 64 20 58 20 61 6e 64 20 pired and X and
43250 4e 20 61 72 65 20 77 69 74 68 69 6e 20 62 6f 75 N are within bou
43260 6e 64 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 nds.**
43270 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c then [sqlite3_bl
43280 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 ob_read(P,Z,N,X)
43290 5d 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 68 ] shall leave th
432a0 65 20 5a 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 e Z buffer.**
432b0 20 20 20 20 20 20 20 75 6e 63 68 61 6e 67 65 64 unchanged
432c0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
432d0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
432e0 2a 20 7b 48 31 37 38 36 35 7d 20 49 66 20 74 68 * {H17865} If th
432f0 65 20 72 65 71 75 65 73 74 65 64 20 72 65 61 64 e requested read
43300 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 6f could not be co
43310 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 20 20 20 20 mpleted,.**
43320 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 the [sqlite
43330 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 3_blob_read(P,Z,
43340 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 N,X)] interface
43350 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 6e 0a shall return an.
43360 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 72 ** appr
43370 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
43380 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 ode] or [extende
43390 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a d error code]..*
433a0 2a 0a 2a 2a 20 7b 48 31 37 38 36 38 7d 20 49 66 *.** {H17868} If
433b0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
433c0 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 during evaluati
433d0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 on of [sqlite3_b
433e0 6c 6f 62 5f 72 65 61 64 28 50 2c 2e 2e 2e 29 5d lob_read(P,...)]
433f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
43400 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
43410 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
43420 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 rrcode(D)],.**
43430 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
43440 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
43450 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 e()],.**
43460 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 [sqlite3_errms
43470 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 g(D)], and [sqli
43480 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d te3_errmsg16(D)]
43490 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a shall return.**
434a0 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d inform
434b0 61 74 69 6f 6e 20 61 70 70 72 6f 70 72 69 61 74 ation appropriat
434c0 65 20 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 e for that error
434d0 2c 20 77 68 65 72 65 20 44 20 69 73 20 74 68 65 , where D is the
434e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
434f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
43500 6e 5d 20 74 68 61 74 20 77 61 73 20 75 73 65 64 n] that was used
43510 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 5b 42 4c to open the [BL
43520 4f 42 20 68 61 6e 64 6c 65 5d 20 50 2e 0a 2a 2f OB handle] P..*/
43530 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
43540 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 b_read(sqlite3_b
43550 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 lob *, void *Z,
43560 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 int N, int iOffs
43570 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 et);../*.** CAPI
43580 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 3REF: Write Data
43590 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 Into A BLOB Inc
435a0 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 rementally {H178
435b0 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 70} <S30230>.**.
435c0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
435d0 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 is used to writ
435e0 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f e data into an o
435f0 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 pen [BLOB handle
43600 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c ] from a.** call
43610 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 er-supplied buff
43620 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 er. N bytes of d
43630 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 ata are copied f
43640 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a rom the buffer Z
43650 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 .** into the ope
43660 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 n BLOB, starting
43670 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 at offset iOffs
43680 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 et..**.** If the
43690 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 [BLOB handle] p
436a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
436b0 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 st argument was
436c0 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a not opened for.*
436d0 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 * writing (the f
436e0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
436f0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f o [sqlite3_blob_
43700 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f open()] was zero
43710 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 ),.** this funct
43720 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ion returns [SQL
43730 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a ITE_READONLY]..*
43740 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
43750 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 on may only modi
43760 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 fy the contents
43770 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 of the BLOB; it
43780 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 is.** not possib
43790 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 le to increase t
437a0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f he size of a BLO
437b0 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 B using this API
437c0 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 ..** If offset i
437d0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 Offset is less t
437e0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d han N bytes from
437f0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
43800 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 BLOB,.** [SQLITE
43810 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 _ERROR] is retur
43820 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 ned and no data
43830 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20 is written. If
43840 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 N is.** less tha
43850 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 n zero [SQLITE_E
43860 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
43870 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
43880 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 written..**.**
43890 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 An attempt to wr
438a0 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 ite to an expire
438b0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 d [BLOB handle]
438c0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a fails with an.**
438d0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b error code of [
438e0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 SQLITE_ABORT].
438f0 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c Writes to the BL
43900 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 OB that occurred
43910 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
43920 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 BLOB handle] exp
43930 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c ired are not rol
43940 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a led back by the.
43950 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 ** expiration of
43960 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f the handle, tho
43970 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
43980 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 ose changes migh
43990 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f t.** have been o
439a0 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 verwritten by th
439b0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 e statement that
439c0 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f expired the BLO
439d0 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 B handle.** or b
439e0 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 y other independ
439f0 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a ent statements..
43a00 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
43a10 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 , SQLITE_OK is r
43a20 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 eturned..** Othe
43a30 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f rwise, an [erro
43a40 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 r code] or an [e
43a50 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
43a60 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
43a70 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
43a80 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 33 S:.**.** {H17873
43a90 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 } A successful i
43aa0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
43ab0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
43ac0 28 50 2c 5a 2c 4e 2c 58 29 5d 0a 2a 2a 20 20 20 (P,Z,N,X)].**
43ad0 20 20 20 20 20 20 20 73 68 61 6c 6c 20 77 72 69 shall wri
43ae0 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 te N bytes of da
43af0 74 61 20 66 72 6f 6d 20 62 75 66 66 65 72 20 5a ta from buffer Z
43b00 20 69 6e 74 6f 20 74 68 65 20 42 4c 4f 42 20 0a into the BLOB .
43b10 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 66 65 ** refe
43b20 72 65 6e 63 65 64 20 62 79 20 5b 42 4c 4f 42 20 renced by [BLOB
43b30 68 61 6e 64 6c 65 5d 20 50 20 62 65 67 69 6e 6e handle] P beginn
43b40 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 58 20 ing at offset X
43b50 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 into.**
43b60 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a the BLOB..**.**
43b70 20 7b 48 31 37 38 37 34 7d 20 49 6e 20 74 68 65 {H17874} In the
43b80 20 61 62 73 65 6e 63 65 20 6f 66 20 6f 74 68 65 absence of othe
43b90 72 20 6f 76 65 72 72 69 64 64 69 6e 67 20 63 68 r overridding ch
43ba0 61 6e 67 65 73 2c 20 74 68 65 20 63 68 61 6e 67 anges, the chang
43bb0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 es.** w
43bc0 72 69 74 74 65 6e 20 74 6f 20 61 20 42 4c 4f 42 ritten to a BLOB
43bd0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f by [sqlite3_blo
43be0 62 5f 77 72 69 74 65 28 29 5d 20 73 68 61 6c 6c b_write()] shall
43bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 6d .** rem
43c00 61 69 6e 20 69 6e 20 65 66 66 65 63 74 20 61 66 ain in effect af
43c10 74 65 72 20 74 68 65 20 61 73 73 6f 63 69 61 74 ter the associat
43c20 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d ed [BLOB handle]
43c30 20 65 78 70 69 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 expires..**.**
43c40 7b 48 31 37 38 37 35 7d 20 49 66 20 74 68 65 20 {H17875} If the
43c50 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 [BLOB handle] P
43c60 77 61 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 was opened for r
43c70 65 61 64 69 6e 67 20 6f 6e 6c 79 20 74 68 65 6e eading only then
43c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 .** an
43c90 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
43ca0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
43cb0 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c e(P,Z,N,X)] shal
43cc0 6c 20 6c 65 61 76 65 0a 2a 2a 20 20 20 20 20 20 l leave.**
43cd0 20 20 20 20 74 68 65 20 72 65 66 65 72 65 6e 63 the referenc
43ce0 65 64 20 42 4c 4f 42 20 75 6e 63 68 61 6e 67 65 ed BLOB unchange
43cf0 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 d and return [SQ
43d00 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a LITE_READONLY]..
43d10 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 36 7d 20 49 **.** {H17876} I
43d20 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 f the size of th
43d30 65 20 42 4c 4f 42 20 72 65 66 65 72 65 6e 63 65 e BLOB reference
43d40 64 20 62 79 20 5b 42 4c 4f 42 20 68 61 6e 64 6c d by [BLOB handl
43d50 65 5d 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 e] P is.**
43d60 20 20 20 20 6c 65 73 73 20 74 68 61 6e 20 4e 2b less than N+
43d70 58 20 62 79 74 65 73 20 74 68 65 6e 20 5b 73 71 X bytes then [sq
43d80 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
43d90 28 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c (P,Z,N,X)] shall
43da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 .** lea
43db0 76 65 20 74 68 65 20 42 4c 4f 42 20 75 6e 63 68 ve the BLOB unch
43dc0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
43dd0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
43de0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 37 7d 20 .**.** {H17877}
43df0 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e If the [BLOB han
43e00 64 6c 65 5d 20 50 20 69 73 20 65 78 70 69 72 65 dle] P is expire
43e10 64 20 61 6e 64 20 58 20 61 6e 64 20 4e 20 61 72 d and X and N ar
43e20 65 20 77 69 74 68 69 6e 20 62 6f 75 6e 64 73 0a e within bounds.
43e30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
43e40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
43e50 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 ead(P,Z,N,X)] sh
43e60 61 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 42 4c all leave the BL
43e70 4f 42 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 OB.** u
43e80 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 nchanged and ret
43e90 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 urn [SQLITE_ABOR
43ea0 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 T]..**.** {H1787
43eb0 39 7d 20 49 66 20 58 20 6f 72 20 4e 20 61 72 65 9} If X or N are
43ec0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 less than zero
43ed0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c then [sqlite3_bl
43ee0 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 ob_write(P,Z,N,X
43ef0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 )].** s
43f00 68 61 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 42 hall leave the B
43f10 4c 4f 42 20 72 65 66 65 72 65 6e 63 65 64 20 62 LOB referenced b
43f20 79 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 y [BLOB handle]
43f30 50 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 20 P unchanged.**
43f40 20 20 20 20 20 20 20 20 61 6e 64 20 72 65 74 75 and retu
43f50 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
43f60 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 38 32 ]..**.** {H17882
43f70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 } The [sqlite3_b
43f80 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c lob_write(P,Z,N,
43f90 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 X)] interface sh
43fa0 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 all return.**
43fb0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f [SQLITE_O
43fc0 4b 5d 20 69 66 20 4e 20 62 79 74 65 73 20 77 68 K] if N bytes wh
43fd0 65 72 65 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ere successfully
43fe0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
43ff0 65 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 7b 48 e BLOB..**.** {H
44000 31 37 38 38 35 7d 20 49 66 20 74 68 65 20 72 65 17885} If the re
44010 71 75 65 73 74 65 64 20 77 72 69 74 65 20 63 6f quested write co
44020 75 6c 64 20 6e 6f 74 20 62 65 20 63 6f 6d 70 6c uld not be compl
44030 65 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 eted,.**
44040 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 the [sqlite3_b
44050 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c lob_write(P,Z,N,
44060 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 X)] interface sh
44070 61 6c 6c 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a all return an.**
44080 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 approp
44090 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
440a0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
440b0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
440c0 2a 2a 20 7b 48 31 37 38 38 38 7d 20 49 66 20 61 ** {H17888} If a
440d0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
440e0 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e uring evaluation
440f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f of [sqlite3_blo
44100 62 5f 77 72 69 74 65 28 44 2c 2e 2e 2e 29 5d 0a b_write(D,...)].
44110 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
44120 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
44130 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
44140 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 rcode(D)],.**
44150 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
44160 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
44170 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
44180 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
44190 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 (D)], and [sqlit
441a0 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20 e3_errmsg16(D)]
441b0 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 shall return.**
441c0 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 informa
441d0 74 69 6f 6e 20 61 70 70 72 6f 70 72 69 61 74 65 tion appropriate
441e0 20 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e for that error.
441f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
44200 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 blob_write(sqlit
44210 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 e3_blob *, const
44220 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c void *z, int n,
44230 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a int iOffset);..
44240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
44250 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 Virtual File Sys
44260 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48 31 31 tem Objects {H11
44270 32 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 200} <S20100>.**
44280 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 .** A virtual fi
44290 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 lesystem (VFS) i
442a0 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 s an [sqlite3_vf
442b0 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 s] object.** tha
442c0 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f t SQLite uses to
442d0 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 interact.** wit
442e0 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 h the underlying
442f0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
44300 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 m. Most SQLite
44310 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 builds come with
44320 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 a.** single def
44330 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 ault VFS that is
44340 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 appropriate for
44350 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 the host comput
44360 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 er..** New VFSes
44370 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 can be register
44380 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 ed and existing
44390 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 VFSes can be unr
443a0 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 egistered..** Th
443b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 e following inte
443c0 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 rfaces are provi
443d0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ded..**.** The s
443e0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
443f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
44400 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
44410 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 a VFS given its
44420 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 name..** Names
44430 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 are case sensiti
44440 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 ve..** Names are
44450 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
44460 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a UTF-8 strings..
44470 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6e ** If there is n
44480 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 o match, a NULL
44490 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
444a0 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 4e ned..** If zVfsN
444b0 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e ame is NULL then
444c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
444d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
444e0 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 .** New VFSes ar
444f0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 e registered wit
44500 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 h sqlite3_vfs_re
44510 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 gister()..** Eac
44520 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 h new VFS become
44530 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 s the default VF
44540 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c S if the makeDfl
44550 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a t flag is set..*
44560 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 * The same VFS c
44570 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 an be registered
44580 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
44590 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a without injury..
445a0 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 ** To make an ex
445b0 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 isting VFS into
445c0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c the default VFS,
445d0 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 register it aga
445e0 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d in.** with the m
445f0 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 akeDflt flag set
44600 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 . If two differ
44610 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74 ent VFSes with t
44620 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 he.** same name
44630 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 are registered,
44640 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
44650 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 undefined. If a
44660 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 .** VFS is regis
44670 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d tered with a nam
44680 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f e that is NULL o
44690 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e r an empty strin
446a0 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 g,.** then the b
446b0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
446c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 ined..**.** Unre
446d0 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 gister a VFS wit
446e0 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 h the sqlite3_vf
446f0 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 s_unregister() i
44700 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 nterface..** If
44710 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
44720 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c is unregistered,
44730 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 another VFS is
44740 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 chosen as.** the
44750 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 default. The c
44760 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 hoice for the ne
44770 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 w VFS is arbitra
44780 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ry..**.** INVARI
44790 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 ANTS:.**.** {H11
447a0 32 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 203} The [sqlite
447b0 33 5f 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20 69 3_vfs_find(N)] i
447c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
447d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
447e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
447f0 67 69 73 74 65 72 65 64 20 5b 73 71 6c 69 74 65 gistered [sqlite
44800 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 77 68 3_vfs] object wh
44810 6f 73 65 20 6e 61 6d 65 20 65 78 61 63 74 6c 79 ose name exactly
44820 20 6d 61 74 63 68 65 73 0a 2a 2a 20 20 20 20 20 matches.**
44830 20 20 20 20 20 74 68 65 20 7a 65 72 6f 2d 74 65 the zero-te
44840 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
44850 74 72 69 6e 67 20 4e 2c 20 6f 72 20 69 74 20 72 tring N, or it r
44860 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 0a 2a eturns NULL if.*
44870 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 72 65 * there
44880 20 69 73 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2a is no match..**
44890 0a 2a 2a 20 7b 48 31 31 32 30 36 7d 20 49 66 20 .** {H11206} If
448a0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
448b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f to [sqlite3_vfs_
448c0 66 69 6e 64 28 4e 29 5d 20 69 73 20 4e 55 4c 4c find(N)] is NULL
448d0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
448e0 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 the function r
448f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
44900 20 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 to the default
44910 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a [sqlite3_vfs].**
44920 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 object
44930 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 if there is one
44940 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 , or NULL if the
44950 72 65 20 69 73 20 6e 6f 20 64 65 66 61 75 6c 74 re is no default
44960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
44970 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
44980 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 30 39 t..**.** {H11209
44990 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
449a0 66 73 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29 fs_register(P,F)
449b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
449c0 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 sters the.**
449d0 20 20 20 20 20 20 77 65 6c 6c 2d 66 6f 72 6d 65 well-forme
449e0 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 d [sqlite3_vfs]
449f0 6f 62 6a 65 63 74 20 50 20 75 73 69 6e 67 20 74 object P using t
44a00 68 65 20 6e 61 6d 65 20 67 69 76 65 6e 0a 2a 2a he name given.**
44a10 20 20 20 20 20 20 20 20 20 20 62 79 20 74 68 65 by the
44a20 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 6f 66 20 zName field of
44a30 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a the object..**.*
44a40 2a 20 7b 48 31 31 32 31 32 7d 20 55 73 69 6e 67 * {H11212} Using
44a50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
44a60 73 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29 5d s_register(P,F)]
44a70 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 72 65 interface to re
44a80 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 gister.**
44a90 20 20 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c the same [sql
44aa0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
44ab0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
44ac0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
44ad0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 -op..**.** {H112
44ae0 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 15} The [sqlite3
44af0 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 50 2c _vfs_register(P,
44b00 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 F)] interface ma
44b10 6b 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 kes the [sqlite3
44b20 5f 76 66 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 _vfs].**
44b30 20 20 6f 62 6a 65 63 74 20 50 20 74 68 65 20 64 object P the d
44b40 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
44b50 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 46 vfs] object if F
44b60 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a is non-zero..**
44b70 0a 2a 2a 20 7b 48 31 31 32 31 38 7d 20 54 68 65 .** {H11218} The
44b80 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e [sqlite3_vfs_un
44b90 72 65 67 69 73 74 65 72 28 50 29 5d 20 69 6e 74 register(P)] int
44ba0 65 72 66 61 63 65 20 75 6e 72 65 67 69 73 74 65 erface unregiste
44bb0 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 rs the.**
44bc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d [sqlite3_vfs]
44bd0 20 6f 62 6a 65 63 74 20 50 20 73 6f 20 74 68 61 object P so tha
44be0 74 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 t it is no longe
44bf0 72 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a r returned by.**
44c00 20 20 20 20 20 20 20 20 20 20 73 75 62 73 65 71 subseq
44c10 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
44c20 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
44c30 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 )]..*/.sqlite3_v
44c40 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f fs *sqlite3_vfs_
44c50 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 find(const char
44c60 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 *zVfsName);.int
44c70 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
44c80 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 ster(sqlite3_vfs
44c90 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 *, int makeDflt)
44ca0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 ;.int sqlite3_vf
44cb0 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c s_unregister(sql
44cc0 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a ite3_vfs*);../*.
44cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
44ce0 65 78 65 73 20 7b 48 31 37 30 30 30 7d 20 3c 53 exes {H17000} <S
44cf0 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20000>.**.** The
44d00 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
44d10 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 s these routines
44d20 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 for thread.** s
44d30 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 ynchronization.
44d40 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 Though they are
44d50 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 intended for int
44d60 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 ernal.** use by
44d70 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 SQLite, code tha
44d80 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
44d90 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 SQLite is.** per
44da0 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e mitted to use an
44db0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
44dc0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 nes..**.** The S
44dd0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 QLite source cod
44de0 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 e contains multi
44df0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
44e00 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 ons.** of these
44e10 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 mutex routines.
44e20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 An appropriate
44e30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
44e40 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 * is selected au
44e50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 tomatically at c
44e60 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 ompile-time. Th
44e70 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 e following.** i
44e80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 mplementations a
44e90 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 re available in
44ea0 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a the SQLite core:
44eb0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
44ec0 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 li> SQLITE_MUT
44ed0 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 EX_OS2.** <li>
44ee0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 SQLITE_MUTEX_PT
44ef0 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 HREAD.** <li>
44f00 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 SQLITE_MUTEX_W32
44f10 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 .** <li> SQLIT
44f20 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 E_MUTEX_NOOP.**
44f30 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
44f40 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f SQLITE_MUTEX_NOO
44f50 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e P implementation
44f60 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 is a set of rou
44f70 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f tines.** that do
44f80 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 es no real locki
44f90 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 ng and is approp
44fa0 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e riate for use in
44fb0 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 .** a single-thr
44fc0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f eaded applicatio
44fd0 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d n. The SQLITE_M
44fe0 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c UTEX_OS2,.** SQL
44ff0 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 ITE_MUTEX_PTHREA
45000 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 D, and SQLITE_MU
45010 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e TEX_W32 implemen
45020 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 tations.** are a
45030 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 ppropriate for u
45040 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 se on OS/2, Unix
45050 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a , and Windows..*
45060 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 *.** If SQLite i
45070 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
45080 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 the SQLITE_MUTEX
45090 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 _APPDEF preproce
450a0 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 ssor.** macro de
450b0 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 fined (with "-DS
450c0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 QLITE_MUTEX_APPD
450d0 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 EF=1"), then no
450e0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 mutex.** impleme
450f0 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 ntation is inclu
45100 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 ded with the lib
45110 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 rary. In this ca
45120 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 se the.** applic
45130 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
45140 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 y a custom mutex
45150 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
45160 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 using the.** [SQ
45170 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
45180 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 X] option of the
45190 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
451a0 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 ) function.** be
451b0 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c fore calling sql
451c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
451d0 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 ) or any other p
451e0 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a ublic sqlite3_.*
451f0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 * function that
45200 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
45210 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a itialize()..**.*
45220 2a 20 7b 48 31 37 30 31 31 7d 20 54 68 65 20 73 * {H17011} The s
45230 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
45240 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c oc() routine all
45250 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 ocates a new.**
45260 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e mutex and return
45270 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
45280 74 2e 20 7b 48 31 37 30 31 32 7d 20 49 66 20 69 t. {H17012} If i
45290 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a t returns NULL.*
452a0 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 * that means tha
452b0 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 t a mutex could
452c0 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 not be allocated
452d0 2e 20 7b 48 31 37 30 31 33 7d 20 53 51 4c 69 74 . {H17013} SQLit
452e0 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 e.** will unwind
452f0 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 its stack and r
45300 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 eturn an error.
45310 7b 48 31 37 30 31 34 7d 20 54 68 65 20 61 72 67 {H17014} The arg
45320 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 ument.** to sqli
45330 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
45340 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 ) is one of thes
45350 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
45360 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a nts:.**.** <ul>.
45370 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
45380 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c MUTEX_FAST.** <l
45390 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 i> SQLITE_MUTEX
453a0 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c _RECURSIVE.** <l
453b0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 i> SQLITE_MUTEX
453c0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a _STATIC_MASTER.*
453d0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
453e0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a UTEX_STATIC_MEM.
453f0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
45400 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
45410 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 2.** <li> SQLIT
45420 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 E_MUTEX_STATIC_P
45430 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c RNG.** <li> SQL
45440 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
45450 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 _LRU.** <li> SQ
45460 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
45470 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a C_LRU2.** </ul>.
45480 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 7d 20 54 **.** {H17015} T
45490 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e he first two con
454a0 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71 6c stants cause sql
454b0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
454c0 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 () to create.**
454d0 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 68 a new mutex. Th
454e0 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 e new mutex is r
454f0 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 ecursive when SQ
45500 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
45510 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 SIVE.** is used
45520 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 but not necessar
45530 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 ily so when SQLI
45540 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 TE_MUTEX_FAST is
45550 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 used. {END}.**
45560 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d The mutex implem
45570 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f entation does no
45580 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 t need to make a
45590 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 distinction.**
455a0 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d between SQLITE_M
455b0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 UTEX_RECURSIVE a
455c0 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f nd SQLITE_MUTEX_
455d0 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a FAST if it does.
455e0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 ** not want to.
455f0 20 7b 48 31 37 30 31 36 7d 20 42 75 74 20 53 51 {H17016} But SQ
45600 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 Lite will only r
45610 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69 equest a recursi
45620 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 ve mutex in.** c
45630 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65 ases where it re
45640 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 ally needs one.
45650 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 73 74 {END} If a fast
45660 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 er non-recursive
45670 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d mutex.** implem
45680 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 entation is avai
45690 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 lable on the hos
456a0 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 t platform, the
456b0 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a mutex subsystem.
456c0 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 ** might return
456d0 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 such a mutex in
456e0 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 response to SQLI
456f0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a TE_MUTEX_FAST..*
45700 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d 20 54 68 *.** {H17017} Th
45710 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 e other allowed
45720 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 parameters to sq
45730 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
45740 63 28 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a c() each return.
45750 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
45760 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73 a static preexis
45770 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44 ting mutex. {END
45780 7d 20 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d } Four static m
45790 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 utexes are.** us
457a0 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e ed by the curren
457b0 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c t version of SQL
457c0 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 ite. Future ver
457d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a sions of SQLite.
457e0 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 ** may add addit
457f0 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 ional static mut
45800 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 exes. Static mu
45810 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e texes are for in
45820 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 ternal.** use by
45830 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 SQLite only. A
45840 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
45850 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 use SQLite mute
45860 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 xes should.** us
45870 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d e only the dynam
45880 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 ic mutexes retur
45890 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 ned by SQLITE_MU
458a0 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 TEX_FAST or.** S
458b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
458c0 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 RSIVE..**.** {H1
458d0 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 74 20 7018} Note that
458e0 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 if one of the dy
458f0 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 namic mutex para
45900 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d meters (SQLITE_M
45910 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 UTEX_FAST.** or
45920 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
45930 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20 URSIVE) is used
45940 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 then sqlite3_mut
45950 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 ex_alloc().** re
45960 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e turns a differen
45970 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 t mutex on every
45980 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30 33 34 7d call. {H17034}
45990 20 42 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 But for the sta
459a0 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 tic.** mutex typ
459b0 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 es, the same mut
459c0 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f ex is returned o
459d0 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 n every call tha
459e0 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d t has.** the sam
459f0 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a e type number..*
45a00 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d 20 54 68 *.** {H17019} Th
45a10 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
45a20 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 free() routine d
45a30 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 eallocates a pre
45a40 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 viously.** alloc
45a50 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 ated dynamic mut
45a60 65 78 2e 20 7b 48 31 37 30 32 30 7d 20 53 51 4c ex. {H17020} SQL
45a70 69 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 ite is careful t
45a80 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 o deallocate eve
45a90 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 ry.** dynamic mu
45aa0 74 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f tex that it allo
45ab0 63 61 74 65 73 2e 20 7b 41 31 37 30 32 31 7d 20 cates. {A17021}
45ac0 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 The dynamic mute
45ad0 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 xes must not be
45ae0 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 in.** use when t
45af0 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 hey are dealloca
45b00 74 65 64 2e 20 7b 41 31 37 30 32 32 7d 20 41 74 ted. {A17022} At
45b10 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c tempting to deal
45b20 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a locate a static.
45b30 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 ** mutex results
45b40 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
45b50 68 61 76 69 6f 72 2e 20 7b 48 31 37 30 32 33 7d havior. {H17023}
45b60 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 SQLite never de
45b70 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 allocates.** a s
45b80 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e tatic mutex. {EN
45b90 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c D}.**.** The sql
45ba0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
45bb0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d () and sqlite3_m
45bc0 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 utex_try() routi
45bd0 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 nes attempt.** t
45be0 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e o enter a mutex.
45bf0 20 7b 48 31 37 30 32 34 7d 20 49 66 20 61 6e 6f {H17024} If ano
45c00 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 ther thread is a
45c10 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 lready within th
45c20 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 e mutex,.** sqli
45c30 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
45c40 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 ) will block and
45c50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
45c60 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e ry() will return
45c70 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e .** SQLITE_BUSY.
45c80 20 7b 48 31 37 30 32 35 7d 20 20 54 68 65 20 73 {H17025} The s
45c90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
45ca0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
45cb0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
45cc0 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 .** upon success
45cd0 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b 48 31 37 ful entry. {H17
45ce0 30 32 36 7d 20 4d 75 74 65 78 65 73 20 63 72 65 026} Mutexes cre
45cf0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 ated using.** SQ
45d00 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
45d10 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65 SIVE can be ente
45d20 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d red multiple tim
45d30 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 es by the same t
45d40 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 hread..** {H1702
45d50 37 7d 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 7} In such cases
45d60 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d the,.** mutex m
45d70 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e ust be exited an
45d80 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 equal number of
45d90 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e times before an
45da0 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 other thread.**
45db0 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31 37 can enter. {A17
45dc0 30 32 38 7d 20 49 66 20 74 68 65 20 73 61 6d 65 028} If the same
45dd0 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f thread tries to
45de0 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 enter any other
45df0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 .** kind of mute
45e00 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 x more than once
45e10 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 , the behavior i
45e20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
45e30 7b 48 31 37 30 32 39 7d 20 53 51 4c 69 74 65 20 {H17029} SQLite
45e40 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 will never exhib
45e50 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 it.** such behav
45e60 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 ior in its own u
45e70 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a se of mutexes..*
45e80 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d *.** Some system
45e90 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 s (for example,
45ea0 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e Windows 95) do n
45eb0 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f ot support the o
45ec0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c peration.** impl
45ed0 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 emented by sqlit
45ee0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 e3_mutex_try().
45ef0 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d On those system
45f00 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 s, sqlite3_mutex
45f10 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 _try().** will a
45f20 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c lways return SQL
45f30 49 54 45 5f 42 55 53 59 2e 20 20 7b 48 31 37 30 ITE_BUSY. {H170
45f40 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 30} The SQLite c
45f50 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 ore only ever us
45f60 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 es.** sqlite3_mu
45f70 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 tex_try() as an
45f80 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 optimization so
45f90 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62 this is acceptab
45fa0 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a le behavior..**.
45fb0 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54 68 65 20 ** {H17031} The
45fc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
45fd0 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 ave() routine ex
45fe0 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 its a mutex that
45ff0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 was.** previous
46000 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 ly entered by th
46010 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 e same thread.
46020 7b 41 31 37 30 33 32 7d 20 54 68 65 20 62 65 68 {A17032} The beh
46030 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 avior.** is unde
46040 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 fined if the mut
46050 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e ex is not curren
46060 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 tly entered by t
46070 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 he.** calling th
46080 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 read or is not c
46090 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 urrently allocat
460a0 65 64 2e 20 20 7b 48 31 37 30 33 33 7d 20 53 51 ed. {H17033} SQ
460b0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 Lite will.** nev
460c0 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20 7b 45 er do either. {E
460d0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ND}.**.** If the
460e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
460f0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
46100 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 (), sqlite3_mute
46110 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 x_try(), or.** s
46120 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
46130 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ve() is a NULL p
46140 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c ointer, then all
46150 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 0a three routines.
46160 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f 2d ** behave as no-
46170 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ops..**.** See a
46180 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 lso: [sqlite3_mu
46190 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 tex_held()] and
461a0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e [sqlite3_mutex_n
461b0 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 otheld()]..*/.sq
461c0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c lite3_mutex *sql
461d0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
461e0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 (int);.void sqli
461f0 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 te3_mutex_free(s
46200 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
46210 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 void sqlite3_mut
46220 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 ex_enter(sqlite3
46230 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 _mutex*);.int sq
46240 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
46250 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
46260 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 .void sqlite3_mu
46270 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 tex_leave(sqlite
46280 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 3_mutex*);../*.*
46290 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
462a0 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 x Methods Object
462b0 20 7b 48 31 37 31 32 30 7d 20 3c 53 32 30 31 33 {H17120} <S2013
462c0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
462d0 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 AL.**.** An inst
462e0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 ance of this str
462f0 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 ucture defines t
46300 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 he low-level rou
46310 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f tines.** used to
46320 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 allocate and us
46330 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a e mutexes..**.**
46340 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 Usually, the de
46350 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c fault mutex impl
46360 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 ementations prov
46370 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 ided by SQLite a
46380 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 re.** sufficient
46390 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 , however the us
463a0 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f er has the optio
463b0 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e n of substitutin
463c0 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d g a custom.** im
463d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 plementation for
463e0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 specialized dep
463f0 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 loyments or syst
46400 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 ems for which SQ
46410 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 Lite.** does not
46420 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 provide a suita
46430 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
46440 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 on. In this case
46450 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 , the user.** cr
46460 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 eates and popula
46470 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 tes an instance
46480 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
46490 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 e to pass.** to
464a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
464b0 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 along with the
464c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
464d0 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a UTEX] option..**
464e0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 Additionally, a
464f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
46500 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e is structure can
46510 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a be used as an.*
46520 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c * output variabl
46530 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 e when querying
46540 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 the system for t
46550 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 he current mutex
46560 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
46570 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 on, using the [S
46580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
46590 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a MUTEX] option..*
465a0 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 *.** The xMutexI
465b0 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e nit method defin
465c0 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 ed by this struc
465d0 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 ture is invoked
465e0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 as.** part of sy
465f0 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 stem initializat
46600 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 ion by the sqlit
46610 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
46620 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 function..** {H1
46630 37 30 30 31 7d 20 54 68 65 20 78 4d 75 74 65 78 7001} The xMutex
46640 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 73 68 61 Init routine sha
46650 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 79 20 ll be called by
46660 53 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72 20 SQLite once for
46670 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 each.** effectiv
46680 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 e call to [sqlit
46690 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
466a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 ..**.** The xMut
466b0 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 exEnd method def
466c0 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 ined by this str
466d0 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 ucture is invoke
466e0 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 d as.** part of
466f0 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 system shutdown
46700 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
46710 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 hutdown() functi
46720 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 on. The.** imple
46730 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 mentation of thi
46740 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 s method is expe
46750 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 cted to release
46760 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a all outstanding.
46770 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 ** resources obt
46780 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 ained by the mut
46790 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 ex methods imple
467a0 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 mentation, espec
467b0 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f ially.** those o
467c0 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 btained by the x
467d0 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 MutexInit method
467e0 2e 20 7b 48 31 37 30 30 33 7d 20 54 68 65 20 78 . {H17003} The x
467f0 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e MutexEnd().** in
46800 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 terface shall be
46810 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
46820 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b r each call to [
46830 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
46840 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 ()]..**.** The r
46850 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d emaining seven m
46860 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 ethods defined b
46870 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
46880 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a (xMutexAlloc,.*
46890 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d * xMutexFree, xM
468a0 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 utexEnter, xMute
468b0 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 xTry, xMutexLeav
468c0 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e e, xMutexHeld an
468d0 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 d.** xMutexNothe
468e0 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 ld) implement th
468f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 e following inte
46900 72 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69 rfaces (respecti
46910 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c vely):.**.** <ul
46920 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
46930 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
46940 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 c()] </li>.**
46950 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
46960 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c utex_free()] </l
46970 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
46980 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
46990 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 er()] </li>.**
469a0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
469b0 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c mutex_try()] </l
469c0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
469d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
469e0 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 ve()] </li>.**
469f0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
46a00 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f mutex_held()] </
46a10 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
46a20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
46a30 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a theld()] </li>.*
46a40 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
46a50 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
46a60 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 e is that the pu
46a70 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 blic sqlite3_XXX
46a80 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 functions enume
46a90 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 rated.** above s
46aa0 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 ilently ignore a
46ab0 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 ny invocations t
46ac0 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 hat pass a NULL
46ad0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a pointer instead.
46ae0 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 ** of a valid mu
46af0 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 tex handle. The
46b00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
46b10 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 of the methods d
46b20 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 efined.** by thi
46b30 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 s structure are
46b40 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
46b50 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 handle this case
46b60 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a , the results.**
46b70 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 of passing a NU
46b80 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 LL pointer inste
46b90 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 ad of a valid mu
46ba0 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 tex handle are u
46bb0 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 ndefined.** (i.e
46bc0 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 . it is acceptab
46bd0 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e le to provide an
46be0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
46bf0 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 that segfaults i
46c00 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 f.** it is passe
46c10 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 d a NULL pointer
46c20 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 )..*/.typedef st
46c30 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 ruct sqlite3_mut
46c40 65 78 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 ex_methods sqlit
46c50 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
46c60 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
46c70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b _mutex_methods {
46c80 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 . int (*xMutexI
46c90 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e nit)(void);. in
46ca0 74 20 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 t (*xMutexEnd)(v
46cb0 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f oid);. sqlite3_
46cc0 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 mutex *(*xMutexA
46cd0 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f lloc)(int);. vo
46ce0 69 64 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29 id (*xMutexFree)
46cf0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
46d00 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 );. void (*xMut
46d10 65 78 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33 exEnter)(sqlite3
46d20 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 _mutex *);. int
46d30 20 28 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71 (*xMutexTry)(sq
46d40 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
46d50 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c void (*xMutexL
46d60 65 61 76 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 eave)(sqlite3_mu
46d70 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a tex *);. int (*
46d80 78 4d 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69 xMutexHeld)(sqli
46d90 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 te3_mutex *);.
46da0 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 int (*xMutexNoth
46db0 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 eld)(sqlite3_mut
46dc0 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ex *);.};../*.**
46dd0 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
46de0 20 56 65 72 69 66 69 63 61 74 69 6f 6e 20 52 6f Verification Ro
46df0 75 74 69 6e 65 73 20 7b 48 31 37 30 38 30 7d 20 utines {H17080}
46e00 3c 53 32 30 31 33 30 3e 20 3c 53 33 30 38 30 30 <S20130> <S30800
46e10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
46e20 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
46e30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
46e40 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 ex_notheld() rou
46e50 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 tines.** are int
46e60 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
46e70 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 side assert() st
46e80 61 74 65 6d 65 6e 74 73 2e 20 7b 48 31 37 30 38 atements. {H1708
46e90 31 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 1} The SQLite co
46ea0 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 re.** never uses
46eb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
46ec0 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e except inside an
46ed0 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 assert() and ap
46ee0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 plications.** ar
46ef0 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c e advised to fol
46f00 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 low the lead of
46f10 74 68 65 20 63 6f 72 65 2e 20 20 7b 48 31 37 30 the core. {H170
46f20 38 32 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 82} The core onl
46f30 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d y.** provides im
46f40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
46f50 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 r these routines
46f60 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 when it is comp
46f70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 iled.** with the
46f80 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c SQLITE_DEBUG fl
46f90 61 67 2e 20 20 7b 41 31 37 30 38 37 7d 20 45 78 ag. {A17087} Ex
46fa0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 ternal mutex imp
46fb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 lementations.**
46fc0 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 are only require
46fd0 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 d to provide the
46fe0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 se routines if S
46ff0 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a QLITE_DEBUG is.*
47000 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 * defined and if
47010 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 NDEBUG is not d
47020 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 efined..**.** {H
47030 31 37 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75 17083} These rou
47040 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74 tines should ret
47050 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 urn true if the
47060 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61 mutex in their a
47070 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 rgument.** is he
47080 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 ld or not held,
47090 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79 respectively, by
470a0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 the calling thr
470b0 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 ead..**.** {X170
470c0 38 34 7d 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 84} The implemen
470d0 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 tation is not re
470e0 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 quired to provid
470f0 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 ed versions of t
47100 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 hese.** routines
47110 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 that actually w
47120 6f 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c ork. If the impl
47130 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 ementation does
47140 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b not provide work
47150 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ing.** versions
47160 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
47170 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 s, it should at
47180 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 least provide st
47190 75 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a ubs that always.
471a0 2a 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 ** return true s
471b0 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 o that one does
471c0 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 not get spurious
471d0 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 assertion failu
471e0 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 res..**.** {H170
471f0 38 35 7d 20 49 66 20 74 68 65 20 61 72 67 75 6d 85} If the argum
47200 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d ent to sqlite3_m
47210 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 utex_held() is a
47220 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
47230 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e en.** the routin
47240 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 e should return
47250 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73 20 73 1. {END} This s
47260 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 eems counter-int
47270 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 uitive since.**
47280 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 clearly the mute
47290 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 x cannot be held
472a0 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 if it does not
472b0 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a exist. But the.
472c0 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 ** the reason th
472d0 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 e mutex does not
472e0 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73 exist is becaus
472f0 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e e the build is n
47300 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 ot.** using mute
47310 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 xes. And we do
47320 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 not want the ass
47330 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 ert() containing
47340 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 the.** call to
47350 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
47360 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f ld() to fail, so
47370 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 a non-zero retu
47380 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 rn is.** the app
47390 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 ropriate thing t
473a0 6f 20 64 6f 2e 20 20 7b 48 31 37 30 38 36 7d 20 o do. {H17086}
473b0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
473c0 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 x_notheld().** i
473d0 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 nterface should
473e0 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68 also return 1 wh
473f0 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 en given a NULL
47400 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 pointer..*/.int
47410 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
47420 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ld(sqlite3_mutex
47430 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
47440 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 mutex_notheld(sq
47450 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a lite3_mutex*);..
47460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
47470 4d 75 74 65 78 20 54 79 70 65 73 20 7b 48 31 37 Mutex Types {H17
47480 30 30 31 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 001} <H17000>.**
47490 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
474a0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 _mutex_alloc()]
474b0 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 interface takes
474c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
474d0 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e t.** which is on
474e0 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 e of these integ
474f0 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a er constants..**
47500 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73 .** The set of s
47510 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61 tatic mutexes ma
47520 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e y change from on
47530 65 20 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65 e SQLite release
47540 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e to the.** next.
47550 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 Applications t
47560 68 61 74 20 6f 76 65 72 72 69 64 65 20 74 68 65 hat override the
47570 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 built-in mutex
47580 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a logic must be.**
47590 20 70 72 65 70 61 72 65 64 20 74 6f 20 61 63 63 prepared to acc
475a0 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f ommodate additio
475b0 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 nal static mutex
475c0 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 es..*/.#define S
475d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
475e0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 0.#
475f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
47600 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 TEX_RECURSIVE
47610 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
47620 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
47630 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 IC_MASTER 2.#
47640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
47650 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 TEX_STATIC_MEM
47660 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 3 /* sqlit
47670 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 e3_malloc() */.#
47680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
47690 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 TEX_STATIC_MEM2
476a0 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 4 /* sqlit
476b0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
476c0 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 y() */.#define S
476d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
476e0 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 IC_PRNG 5
476f0 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f /* sqlite3_rando
47700 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 m() */.#define S
47710 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
47720 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 IC_LRU 6
47730 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 /* lru page list
47740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
47750 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
47760 4c 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 LRU2 7 /*
47770 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f lru page list */
47780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
47790 3a 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d : Retrieve the m
477a0 75 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 utex for a datab
477b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b ase connection {
477c0 48 31 37 30 30 32 7d 20 3c 48 31 37 30 30 30 3e H17002} <H17000>
477d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
477e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
477f0 70 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c pointer the [sql
47800 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 ite3_mutex] obje
47810 63 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 ct that .** seri
47820 61 6c 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f alizes access to
47830 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
47840 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e onnection] given
47850 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 in the argument
47860 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 .** when the [th
47870 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
47880 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 Serialized..**
47890 49 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e If the [threadin
478a0 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c g mode] is Singl
478b0 65 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 e-thread or Mult
478c0 69 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 i-thread then th
478d0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 is.** routine re
478e0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
478f0 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 nter..*/.sqlite3
47900 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f _mutex *sqlite3_
47910 64 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 db_mutex(sqlite3
47920 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
47930 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 REF: Low-Level C
47940 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 ontrol Of Databa
47950 73 65 20 46 69 6c 65 73 20 7b 48 31 31 33 30 30 se Files {H11300
47960 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a } <S30800>.**.**
47970 20 7b 48 31 31 33 30 31 7d 20 54 68 65 20 5b 73 {H11301} The [s
47980 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
47990 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
479a0 20 6d 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 makes a direct
479b0 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 call to the.** x
479c0 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
479d0 6f 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 od for the [sqli
479e0 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
479f0 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 object associate
47a00 64 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 d.** with a part
47a10 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 icular database
47a20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
47a30 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
47a40 74 2e 20 7b 48 31 31 33 30 32 7d 20 54 68 65 0a t. {H11302} The.
47a50 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 ** name of the d
47a60 61 74 61 62 61 73 65 20 69 73 20 74 68 65 20 6e atabase is the n
47a70 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 ame assigned to
47a80 74 68 65 20 64 61 74 61 62 61 73 65 20 62 79 20 the database by
47a90 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
47aa0 6c 61 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c lang_attach.html
47ab0 22 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c ">ATTACH</a> SQL
47ac0 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 command that op
47ad0 65 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 ened the.** data
47ae0 62 61 73 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 base. {H11303} T
47af0 6f 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 o control the ma
47b00 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
47b10 2c 20 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 , use the name "
47b20 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 main".** or a NU
47b30 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 LL pointer. {H11
47b40 33 30 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 304} The third a
47b50 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 nd fourth parame
47b60 74 65 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 ters to this rou
47b70 74 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 tine.** are pass
47b80 65 64 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f ed directly thro
47b90 75 67 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e ugh to the secon
47ba0 64 20 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 d and third para
47bb0 6d 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 meters of.** the
47bc0 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
47bd0 74 68 6f 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 thod. {H11305}
47be0 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
47bf0 20 6f 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e of the xFileCon
47c00 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 trol.** method b
47c10 65 63 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 ecomes the retur
47c20 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
47c30 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b routine..**.** {
47c40 48 31 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 H11306} If the s
47c50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
47c60 28 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e (zDbName) does n
47c70 6f 74 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d ot match the nam
47c80 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e e of any.** open
47c90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
47ca0 74 68 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f then SQLITE_ERRO
47cb0 52 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b R is returned. {
47cc0 48 31 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 H11307} This err
47cd0 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f or.** code is no
47ce0 74 20 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 t remembered and
47cf0 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 will not be rec
47d00 61 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 alled by [sqlite
47d10 33 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 3_errcode()].**
47d20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
47d30 73 67 28 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 sg()]. {A11308}
47d40 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 The underlying x
47d50 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
47d60 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f od might.** also
47d70 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 return SQLITE_E
47d80 52 52 4f 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 RROR. {A11309}
47d90 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 There is no way
47da0 74 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 to distinguish b
47db0 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 etween.** an inc
47dc0 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 orrect zDbName a
47dd0 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 nd an SQLITE_ERR
47de0 4f 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 OR return from t
47df0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a he underlying.**
47e00 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
47e10 74 68 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a thod. {END}.**.*
47e20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c * See also: [SQL
47e30 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
47e40 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ATE].*/.int sqli
47e50 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
47e60 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 (sqlite3*, const
47e70 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 char *zDbName,
47e80 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a int op, void*);.
47e90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
47ea0 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 Testing Interfa
47eb0 63 65 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 30 ce {H11400} <S30
47ec0 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 800>.**.** The s
47ed0 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 qlite3_test_cont
47ee0 72 6f 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 rol() interface
47ef0 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 is used to read
47f00 6f 75 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 out internal.**
47f10 73 74 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 state of SQLite
47f20 61 6e 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 and to inject fa
47f30 75 6c 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 ults into SQLite
47f40 20 66 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 for testing.**
47f50 70 75 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 purposes. The f
47f60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
47f70 73 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 s an operation c
47f80 6f 64 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 ode that determi
47f90 6e 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 nes.** the numbe
47fa0 72 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 r, meaning, and
47fb0 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c operation of all
47fc0 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 subsequent para
47fd0 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 meters..**.** Th
47fe0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
47ff0 6e 6f 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 not for use by a
48000 70 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 pplications. It
48010 20 65 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a exists solely.*
48020 2a 20 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 * for verifying
48030 74 68 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 the correct oper
48040 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c ation of the SQL
48050 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 ite library. De
48060 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f pending.** on ho
48070 77 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 w the SQLite lib
48080 72 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 rary is compiled
48090 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 , this interface
480a0 20 6d 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 might not exist
480b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 ..**.** The deta
480c0 69 6c 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 ils of the opera
480d0 74 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 tion codes, thei
480e0 72 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 r meanings, the
480f0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 parameters.** th
48100 65 79 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 ey take, and wha
48110 74 20 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c t they do are al
48120 6c 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 l subject to cha
48130 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 nge without noti
48140 63 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f ce..** Unlike mo
48150 73 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 st of the SQLite
48160 20 41 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 API, this funct
48170 69 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 ion is not guara
48180 6e 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 nteed to.** oper
48190 61 74 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 ate consistently
481a0 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 from one releas
481b0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
481c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 /.int sqlite3_te
481d0 73 74 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f st_control(int o
481e0 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 p, ...);../*.**
481f0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e CAPI3REF: Testin
48200 67 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 g Interface Oper
48210 61 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 ation Codes {H11
48220 34 31 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 410} <H11400>.**
48230 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
48240 6e 74 73 20 61 72 65 20 74 68 65 20 76 61 6c 69 nts are the vali
48250 64 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 d operation code
48260 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 65 64 parameters used
48270 0a 2a 2a 20 61 73 20 74 68 65 20 66 69 72 73 74 .** as the first
48280 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
48290 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 lite3_test_contr
482a0 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ol()]..**.** The
482b0 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e se parameters an
482c0 64 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 d their meanings
482d0 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 are subject to
482e0 63 68 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 change.** withou
482f0 74 20 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 65 t notice. These
48300 20 76 61 6c 75 65 73 20 61 72 65 20 66 6f 72 20 values are for
48310 74 65 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 testing purposes
48320 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 only..** Applic
48330 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f ations should no
48340 74 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 t use any of the
48350 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 se parameters or
48360 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
48370 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d _test_control()]
48380 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 interface..*/.#
48390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
483a0 53 54 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 STCTRL_PRNG_SAVE
483b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
483c0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
483d0 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 _TESTCTRL_PRNG_R
483e0 45 53 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 ESTORE
483f0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 6.#define SQL
48400 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e ITE_TESTCTRL_PRN
48410 47 5f 52 45 53 45 54 20 20 20 20 20 20 20 20 20 G_RESET
48420 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
48430 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
48440 42 49 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 BITVEC_TEST
48450 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 8.#defi
48460 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
48470 52 4c 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c RL_FAULT_INSTALL
48480 20 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 9.#d
48490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
484a0 54 43 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c TCTRL_BENIGN_MAL
484b0 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 LOC_HOOKS 10
484c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
484d0 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 : SQLite Runtime
484e0 20 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d Status {H17200}
484f0 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 <S60200>.** EXP
48500 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
48510 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 This interface i
48520 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 s used to retrie
48530 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 ve runtime statu
48540 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a s information.**
48550 20 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f about the prefo
48560 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 rmance of SQLite
48570 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 , and optionally
48580 20 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 to reset variou
48590 73 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d s.** highwater m
485a0 61 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 arks. The first
485b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
485c0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 integer code for
485d0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 .** the specific
485e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 parameter to me
485f0 61 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a asure. Recogniz
48600 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ed integer codes
48610 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 .** are of the f
48620 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 orm [SQLITE_STAT
48630 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c US_MEMORY_USED |
48640 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e SQLITE_STATUS_.
48650 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 ..]..** The curr
48660 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 ent value of the
48670 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 parameter is re
48680 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 turned into *pCu
48690 72 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 rrent..** The hi
486a0 67 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 ghest recorded v
486b0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
486c0 20 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e in *pHighwater.
486d0 20 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 If the.** rese
486e0 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 tFlag is true, t
486f0 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 hen the highest
48700 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 record value is
48710 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a reset after.** *
48720 70 48 69 67 68 77 61 74 65 72 20 69 73 20 77 72 pHighwater is wr
48730 69 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 itten. Some para
48740 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 meters do not re
48750 63 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 74 cord the highest
48760 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 .** value. For
48770 74 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 those parameters
48780 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 .** nothing is w
48790 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 ritten into *pHi
487a0 67 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 ghwater and the
487b0 72 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e resetFlag is ign
487c0 6f 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 ored..** Other p
487d0 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 arameters record
487e0 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 only the highwa
487f0 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 ter mark and not
48800 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
48810 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 value. For thes
48820 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 e latter paramet
48830 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 ers nothing is w
48840 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 ritten into *pCu
48850 72 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 rrent..**.** Thi
48860 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
48870 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 s SQLITE_OK on s
48880 75 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e uccess and a non
48890 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 -zero.** [error
488a0 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 code] on failure
488b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
488c0 74 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 tine is threadsa
488d0 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 fe but is not at
488e0 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 omic. This rout
488f0 69 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 ine can.** calle
48900 64 20 77 68 69 6c 65 20 6f 74 68 65 72 20 74 68 d while other th
48910 72 65 61 64 73 20 61 72 65 20 72 75 6e 6e 69 6e reads are runnin
48920 67 20 74 68 65 20 73 61 6d 65 20 6f 72 20 64 69 g the same or di
48930 66 66 65 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a fferent SQLite.*
48940 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 * interfaces. H
48950 6f 77 65 76 65 72 20 74 68 65 20 76 61 6c 75 65 owever the value
48960 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 s returned in *p
48970 43 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a Current and.** *
48980 70 48 69 67 68 77 61 74 65 72 20 72 65 66 6c 65 pHighwater refle
48990 63 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ct the status of
489a0 20 53 51 4c 69 74 65 20 61 74 20 64 69 66 66 65 SQLite at diffe
489b0 72 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 rent points in t
489c0 69 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 ime.** and it is
489d0 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 possible that a
489e0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 69 nother thread mi
489f0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 70 ght change the p
48a00 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 arameter.** in b
48a10 65 74 77 65 65 6e 20 74 68 65 20 74 69 6d 65 73 etween the times
48a20 20 77 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 when *pCurrent
48a30 61 6e 64 20 2a 70 48 69 67 68 77 61 74 65 72 20 and *pHighwater
48a40 61 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a are written..**.
48a50 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
48a60 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 lite3_db_status(
48a70 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 )].*/.SQLITE_EXP
48a80 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 ERIMENTAL int sq
48a90 6c 69 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 lite3_status(int
48aa0 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 op, int *pCurre
48ab0 6e 74 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 nt, int *pHighwa
48ac0 74 65 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c ter, int resetFl
48ad0 61 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ag);.../*.** CAP
48ae0 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 I3REF: Status Pa
48af0 72 61 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 rameters {H17250
48b00 7d 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 } <H17200>.** EX
48b10 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
48b20 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
48b30 6f 6e 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 onstants designa
48b40 74 65 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 te various run-t
48b50 69 6d 65 20 73 74 61 74 75 73 20 70 61 72 61 6d ime status param
48b60 65 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 eters.** that ca
48b70 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 n be returned by
48b80 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
48b90 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ()]..**.** <dl>.
48ba0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
48bb0 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 ATUS_MEMORY_USED
48bc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
48bd0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 s parameter is t
48be0 68 65 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e he current amoun
48bf0 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 t of memory chec
48c00 6b 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 ked out.** using
48c10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
48c20 28 29 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 ()], either dire
48c30 63 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 ctly or indirect
48c40 6c 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 ly. The.** figu
48c50 72 65 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c re includes call
48c60 73 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 s made to [sqlit
48c70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 e3_malloc()] by
48c80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a the application.
48c90 2a 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 ** and internal
48ca0 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 memory usage by
48cb0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
48cc0 72 79 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d ry. Scratch mem
48cd0 6f 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 ory.** controlle
48ce0 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e d by [SQLITE_CON
48cf0 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 FIG_SCRATCH] and
48d00 20 61 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d auxiliary page-
48d10 63 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 cache.** memory
48d20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 controlled by [S
48d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
48d40 45 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 ECACHE] is not i
48d50 6e 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 ncluded in.** th
48d60 69 73 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 is parameter. T
48d70 68 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e he amount return
48d80 65 64 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 ed is the sum of
48d90 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a the allocation.
48da0 2a 2a 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f ** sizes as repo
48db0 72 74 65 64 20 62 79 20 74 68 65 20 78 53 69 7a rted by the xSiz
48dc0 65 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c e method in [sql
48dd0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
48de0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 ].</dd>.**.** <d
48df0 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
48e00 4d 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e MALLOC_SIZE</dt>
48e10 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
48e20 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 ameter records t
48e30 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 he largest memor
48e40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
48e50 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 uest.** handed t
48e60 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
48e70 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
48e80 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 _realloc()] (or
48e90 74 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 their.** interna
48ea0 6c 20 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 l equivalents).
48eb0 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 Only the value
48ec0 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a returned in the.
48ed0 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 ** *pHighwater p
48ee0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
48ef0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 ite3_status()] i
48f00 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 s of interest.
48f10 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 .** The value wr
48f20 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a itten into the *
48f30 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 pCurrent paramet
48f40 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e er is undefined.
48f50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
48f60 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 SQLITE_STATUS_PA
48f70 47 45 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 GECACHE_USED</dt
48f80 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
48f90 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 rameter returns
48fa0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
48fb0 67 65 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 ges used out of
48fc0 74 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 the.** [pagecach
48fd0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
48fe0 6f 72 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e or] that was con
48ff0 66 69 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a figured using .*
49000 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
49010 5f 50 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 _PAGECACHE]. Th
49020 65 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 e.** value retur
49030 6e 65 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c ned is in pages,
49040 20 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f not in bytes.</
49050 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
49060 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
49070 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f CACHE_OVERFLOW</
49080 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
49090 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
490a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
490b0 62 79 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 bytes of page ca
490c0 63 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f che.** allocatio
490d0 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f n which could no
490e0 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64 20 t be statisfied
490f0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 by the [SQLITE_C
49100 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
49110 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 .** buffer and w
49120 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f here forced to o
49130 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 verflow to [sqli
49140 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 te3_malloc()].
49150 54 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 The.** returned
49160 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 value includes a
49170 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 llocations that
49180 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 overflowed becau
49190 73 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 se they.** where
491a0 20 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 too large (they
491b0 20 77 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 were larger tha
491c0 6e 20 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d n the "sz" param
491d0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 eter to.** [SQLI
491e0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
491f0 43 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 CHE]) and alloca
49200 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 tions that overf
49210 6c 6f 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a lowed because.**
49220 20 6e 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 no space was le
49230 66 74 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 ft in the page c
49240 61 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ache.</dd>.**.**
49250 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
49260 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a US_PAGECACHE_SIZ
49270 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
49280 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 is parameter rec
49290 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 ords the largest
492a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
492b0 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 on request.** ha
492c0 6e 64 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 nded to [pagecac
492d0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
492e0 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 tor]. Only the
492f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 value returned i
49300 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 n the.** *pHighw
49310 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 ater parameter t
49320 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 o [sqlite3_statu
49330 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 s()] is of inter
49340 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 est. .** The va
49350 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f lue written into
49360 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 the *pCurrent p
49370 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 arameter is unde
49380 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a fined.</dd>.**.*
49390 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
493a0 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 TUS_SCRATCH_USED
493b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
493c0 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 s parameter retu
493d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
493e0 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 f allocations us
493f0 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a ed out of the.**
49400 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 [scratch memory
49410 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 allocator] conf
49420 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 igured using.**
49430 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
49440 43 52 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 CRATCH]. The va
49450 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
49460 69 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 in allocations,
49470 6e 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e not.** in bytes.
49480 20 20 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 Since a single
49490 20 74 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 thread may only
494a0 20 68 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 have one scratc
494b0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 h allocation.**
494c0 6f 75 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 outstanding at t
494d0 69 6d 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 ime, this parame
494e0 74 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 ter also reports
494f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 the number of t
49500 68 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 hreads.** using
49510 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 scratch memory a
49520 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
49530 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
49540 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 SQLITE_STATUS_SC
49550 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f RATCH_OVERFLOW</
49560 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
49570 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
49580 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
49590 62 79 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 bytes of scratch
495a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
495b0 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c ation which coul
495c0 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 d not be statisf
495d0 69 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 ied by the [SQLI
495e0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
495f0 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 H].** buffer and
49600 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f where forced to
49610 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 overflow to [sq
49620 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
49630 20 20 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 The values.**
49640 72 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 returned include
49650 20 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 overflows becau
49660 73 65 20 74 68 65 20 72 65 71 75 65 73 74 65 64 se the requested
49670 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 allocation was
49680 74 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 too.** larger (t
49690 68 61 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 hat is, because
496a0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c the requested al
496b0 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 location was lar
496c0 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 ger than the.**
496d0 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 "sz" parameter t
496e0 6f 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 o [SQLITE_CONFIG
496f0 5f 53 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 _SCRATCH]) and b
49700 65 63 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 ecause no scratc
49710 68 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 h buffer.** slot
49720 73 20 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 s were available
49730 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
49740 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
49750 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c US_SCRATCH_SIZE<
49760 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
49770 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 parameter recor
49780 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d ds the largest m
49790 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
497a0 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 request.** hand
497b0 65 64 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d ed to [scratch m
497c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
497d0 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 . Only the valu
497e0 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 e returned in th
497f0 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 e.** *pHighwater
49800 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
49810 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
49820 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e is of interest.
49830 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 .** The value
49840 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
49850 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d *pCurrent param
49860 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 eter is undefine
49870 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
49880 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
49890 50 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 PARSER_STACK</dt
498a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
498b0 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 rameter records
498c0 74 68 65 20 64 65 65 70 65 73 74 20 70 61 72 73 the deepest pars
498d0 65 72 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 er stack. It is
498e0 20 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 only.** meaning
498f0 66 75 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 ful if SQLite is
49900 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
49910 59 59 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 YYTRACKMAXSTACKD
49920 45 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c EPTH].</dd>.** <
49930 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 /dl>.**.** New s
49940 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 tatus parameters
49950 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 66 72 may be added fr
49960 6f 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e om time to time.
49970 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
49980 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 TE_STATUS_MEMORY
49990 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 20 30 _USED 0
499a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
499b0 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 STATUS_PAGECACHE
499c0 5f 55 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 _USED 1.#d
499d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
499e0 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 TUS_PAGECACHE_OV
499f0 45 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 ERFLOW 2.#defi
49a00 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 ne SQLITE_STATUS
49a10 5f 53 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 _SCRATCH_USED
49a20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
49a30 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 SQLITE_STATUS_SC
49a40 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 RATCH_OVERFLOW
49a50 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
49a60 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f ITE_STATUS_MALLO
49a70 43 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 C_SIZE
49a80 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
49a90 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 _STATUS_PARSER_S
49aa0 54 41 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 TACK 6.#
49ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
49ac0 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 ATUS_PAGECACHE_S
49ad0 49 5a 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 IZE 7.#def
49ae0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
49af0 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 S_SCRATCH_SIZE
49b00 20 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 8../*.**
49b10 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
49b20 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 se Connection St
49b30 61 74 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 atus {H17500} <S
49b40 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 60200>.** EXPERI
49b50 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 MENTAL.**.** Thi
49b60 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 s interface is u
49b70 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
49b80 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 runtime status i
49b90 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 nformation .** a
49ba0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 bout a single [d
49bb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
49bc0 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 on]. The first
49bd0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a argument is the.
49be0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
49bf0 65 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f ection object to
49c00 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 be interrogated
49c10 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
49c20 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 gument.** is the
49c30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e parameter to in
49c40 74 65 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 terrogate. Curr
49c50 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 ently, the only
49c60 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a allowed value.**
49c70 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 for the second
49c80 70 61 72 61 6d 65 74 65 72 20 69 73 20 5b 53 51 parameter is [SQ
49c90 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f LITE_DBSTATUS_LO
49ca0 4f 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a OKASIDE_USED]..*
49cb0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 * Additional opt
49cc0 69 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 ions will likely
49cd0 20 61 70 70 65 61 72 20 69 6e 20 66 75 74 75 72 appear in futur
49ce0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
49cf0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
49d00 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 current value of
49d10 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 the requested p
49d20 61 72 61 6d 65 74 65 72 20 69 73 20 77 72 69 74 arameter is writ
49d30 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a ten into *pCur.*
49d40 2a 20 61 6e 64 20 74 68 65 20 68 69 67 68 65 73 * and the highes
49d50 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 t instantaneous
49d60 76 61 6c 75 65 20 69 73 20 77 72 69 74 74 65 6e value is written
49d70 20 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 into *pHiwtr.
49d80 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 46 If.** the resetF
49d90 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e lg is true, then
49da0 20 74 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 the highest ins
49db0 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 tantaneous value
49dc0 20 69 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 is.** reset bac
49dd0 6b 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 k down to the cu
49de0 72 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a rrent value..**.
49df0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
49e00 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 lite3_status()]
49e10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d and [sqlite3_stm
49e20 74 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a t_status()]..*/.
49e30 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
49e40 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
49e50 64 62 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 db_status(sqlite
49e60 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 3*, int op, int
49e70 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 *pCur, int *pHiw
49e80 74 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 67 tr, int resetFlg
49e90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
49ea0 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d EF: Status Param
49eb0 65 74 65 72 73 20 66 6f 72 20 64 61 74 61 62 61 eters for databa
49ec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b se connections {
49ed0 48 31 37 35 32 30 7d 20 3c 48 31 37 35 30 30 3e H17520} <H17500>
49ee0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
49ef0 0a 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 .**.** Status ve
49f00 72 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 rbs for [sqlite3
49f10 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a _db_status()]..*
49f20 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
49f30 3e 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 >SQLITE_DBSTATUS
49f40 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c _LOOKASIDE_USED<
49f50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
49f60 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
49f70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
49f80 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
49f90 79 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c y slots currentl
49fa0 79 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 y.** checked out
49fb0 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a .</dd>.** </dl>.
49fc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
49fd0 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 E_DBSTATUS_LOOKA
49fe0 53 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 0a SIDE_USED 0.
49ff0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4a000 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 : Prepared State
4a010 6d 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 37 ment Status {H17
4a020 35 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 550} <S60200>.**
4a030 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
4a040 0a 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 65 .** Each prepare
4a050 64 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e d statement main
4a060 74 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a tains various.**
4a070 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 [SQLITE_STMTSTA
4a080 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 TUS_SORT | count
4a090 65 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 72 ers] that measur
4a0a0 65 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 e the number.**
4a0b0 6f 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 20 of times it has
4a0c0 70 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 66 performed specif
4a0d0 69 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 ic operations.
4a0e0 54 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 63 These counters c
4a0f0 61 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f an.** be used to
4a100 20 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 72 monitor the per
4a110 66 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 74 formance charact
4a120 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 eristics of the
4a130 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
4a140 65 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 ements. For exa
4a150 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 6d mple, if the num
4a160 62 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 65 ber of table ste
4a170 70 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 65 ps greatly excee
4a180 64 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 ds.** the number
4a190 20 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 68 of table search
4a1a0 65 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 es or result row
4a1b0 73 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 65 s, that would te
4a1c0 6e 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a nd to indicate.*
4a1d0 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 * that the prepa
4a1e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 red statement is
4a1f0 20 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 using a full ta
4a200 62 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 20 ble scan rather
4a210 74 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 than.** an index
4a220 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 . .**.** This i
4a230 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
4a240 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e 64 to retrieve and
4a250 20 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 76 reset counter v
4a260 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 alues from.** a
4a270 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
4a280 65 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ent]. The first
4a290 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
4a2a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
4a2b0 65 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f ent.** object to
4a2c0 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 be interrogated
4a2d0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
4a2e0 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 gument.** is an
4a2f0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 integer code for
4a300 20 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c a specific [SQL
4a310 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 ITE_STMTSTATUS_S
4a320 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a ORT | counter].*
4a330 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 * to be interrog
4a340 61 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 ated. .** The cu
4a350 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 rrent value of t
4a360 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 75 he requested cou
4a370 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
4a380 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 65 ..** If the rese
4a390 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 tFlg is true, th
4a3a0 65 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 69 en the counter i
4a3b0 73 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 s reset to zero
4a3c0 61 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e after this.** in
4a3d0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 74 terface call ret
4a3e0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 urns..**.** See
4a3f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 also: [sqlite3_s
4a400 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 tatus()] and [sq
4a410 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 lite3_db_status(
4a420 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 )]..*/.SQLITE_EX
4a430 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
4a440 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 qlite3_stmt_stat
4a450 75 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a us(sqlite3_stmt*
4a460 2c 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 , int op,int res
4a470 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 etFlg);../*.** C
4a480 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 API3REF: Status
4a490 50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 70 Parameters for p
4a4a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
4a4b0 74 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 ts {H17570} <H17
4a4c0 35 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 550>.** EXPERIME
4a4d0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 NTAL.**.** These
4a4e0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
4a4f0 63 72 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 65 cros define inte
4a500 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 6e ger codes that n
4a510 61 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 ame counter.** v
4a520 61 6c 75 65 73 20 61 73 73 6f 63 69 61 74 65 64 alues associated
4a530 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 with the [sqlit
4a540 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 e3_stmt_status()
4a550 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 ] interface..**
4a560 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 The meanings of
4a570 74 68 65 20 76 61 72 69 6f 75 73 20 63 6f 75 6e the various coun
4a580 74 65 72 73 20 61 72 65 20 61 73 20 66 6f 6c 6c ters are as foll
4a590 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ows:.**.** <dl>.
4a5a0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
4a5b0 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 MTSTATUS_FULLSCA
4a5c0 4e 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c N_STEP</dt>.** <
4a5d0 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e dd>This is the n
4a5e0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 umber of times t
4a5f0 68 61 74 20 53 51 4c 69 74 65 20 68 61 73 20 73 hat SQLite has s
4a600 74 65 70 70 65 64 20 66 6f 72 77 61 72 64 20 69 tepped forward i
4a610 6e 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 20 n.** a table as
4a620 70 61 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 part of a full t
4a630 61 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 able scan. Larg
4a640 65 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 68 e numbers for th
4a650 69 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 is counter.** ma
4a660 79 20 69 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 y indicate oppor
4a670 74 75 6e 69 74 69 65 73 20 66 6f 72 20 70 65 72 tunities for per
4a680 66 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 formance improve
4a690 6d 65 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a ment through .**
4a6a0 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 20 careful use of
4a6b0 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a indices.</dd>.**
4a6c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
4a6d0 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f TMTSTATUS_SORT</
4a6e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
4a6f0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
4a700 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 sort operations
4a710 20 74 68 61 74 20 68 61 76 65 20 6f 63 63 75 72 that have occur
4a720 72 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 red..** A non-ze
4a730 72 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 73 ro value in this
4a740 20 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 counter may ind
4a750 69 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 icate an opportu
4a760 6e 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f nity to.** impro
4a770 76 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e vement performan
4a780 63 65 20 74 68 72 6f 75 67 68 20 63 61 72 65 66 ce through caref
4a790 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 ul use of indice
4a7a0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f s.</dd>.**.** </
4a7b0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
4a7c0 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 QLITE_STMTSTATUS
4a7d0 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 _FULLSCAN_STEP
4a7e0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
4a7f0 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 ITE_STMTSTATUS_S
4a800 4f 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ORT
4a810 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 2../*.** CAPI3R
4a820 45 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 20 EF: Custom Page
4a830 43 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 Cache Object.**
4a840 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
4a850 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 ** The sqlite3_p
4a860 63 61 63 68 65 20 74 79 70 65 20 69 73 20 6f 70 cache type is op
4a870 61 71 75 65 2e 20 20 49 74 20 69 73 20 69 6d 70 aque. It is imp
4a880 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 lemented by.** t
4a890 68 65 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 he pluggable mod
4a8a0 75 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 ule. The SQLite
4a8b0 20 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f core has no kno
4a8c0 77 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 wledge of.** its
4a8d0 20 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 size or interna
4a8e0 6c 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 l structure and
4a8f0 6e 65 76 65 72 20 64 65 61 6c 73 20 77 69 74 68 never deals with
4a900 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
4a910 70 63 61 63 68 65 20 6f 62 6a 65 63 74 20 65 78 pcache object ex
4a920 63 65 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 cept by holding
4a930 61 6e 64 20 70 61 73 73 69 6e 67 20 70 6f 69 6e and passing poin
4a940 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f ters.** to the o
4a950 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 bject..**.** See
4a960 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
4a970 5f 6d 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 _methods] for ad
4a980 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
4a990 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
4a9a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
4a9b0 70 63 61 63 68 65 20 73 71 6c 69 74 65 33 5f 70 pcache sqlite3_p
4a9c0 63 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 cache;../*.** CA
4a9d0 50 49 33 52 45 46 3a 20 41 70 70 6c 69 63 61 74 PI3REF: Applicat
4a9e0 69 6f 6e 20 44 65 66 69 6e 65 64 20 50 61 67 65 ion Defined Page
4a9f0 20 43 61 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 Cache..** EXPER
4aa00 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
4aa10 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
4aa20 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
4aa30 47 5f 50 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 G_PCACHE], ...)
4aa40 69 6e 74 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a interface can.**
4aa50 20 72 65 67 69 73 74 65 72 20 61 6e 20 61 6c 74 register an alt
4aa60 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 ernative page ca
4aa70 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
4aa80 6f 6e 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e on by passing in
4aa90 20 61 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 an .** instance
4aaa0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
4aab0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 pcache_methods s
4aac0 74 72 75 63 74 75 72 65 2e 20 54 68 65 20 6d 61 tructure. The ma
4aad0 6a 6f 72 69 74 79 20 6f 66 20 74 68 65 20 0a 2a jority of the .*
4aae0 2a 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 * heap memory us
4aaf0 65 64 20 62 79 20 73 71 6c 69 74 65 20 69 73 20 ed by sqlite is
4ab00 75 73 65 64 20 62 79 20 74 68 65 20 70 61 67 65 used by the page
4ab10 20 63 61 63 68 65 20 74 6f 20 63 61 63 68 65 20 cache to cache
4ab20 64 61 74 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 data read .** fr
4ab30 6f 6d 2c 20 6f 72 20 72 65 61 64 79 20 74 6f 20 om, or ready to
4ab40 62 65 20 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 be written to, t
4ab50 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
4ab60 2e 20 42 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e . By implementin
4ab70 67 20 61 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 g a .** custom p
4ab80 61 67 65 20 63 61 63 68 65 20 75 73 69 6e 67 20 age cache using
4ab90 74 68 69 73 20 41 50 49 2c 20 61 6e 20 61 70 70 this API, an app
4aba0 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e lication can con
4abb0 74 72 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 trol more .** pr
4abc0 65 63 69 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 ecisely the amou
4abd0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e nt of memory con
4abe0 73 75 6d 65 64 20 62 79 20 73 71 6c 69 74 65 2c sumed by sqlite,
4abf0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
4ac00 68 20 0a 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 h .** said memor
4ac10 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 y is allocated a
4ac20 6e 64 20 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 nd released, and
4ac30 20 74 68 65 20 70 6f 6c 69 63 69 65 73 20 75 73 the policies us
4ac40 65 64 20 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d ed to .** determ
4ac50 69 6e 65 20 65 78 61 63 74 6c 79 20 77 68 69 63 ine exactly whic
4ac60 68 20 70 61 72 74 73 20 6f 66 20 61 20 64 61 74 h parts of a dat
4ac70 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 63 abase file are c
4ac80 61 63 68 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a ached and for .*
4ac90 2a 20 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a * how long..**.*
4aca0 2a 20 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f * The contents o
4acb0 66 20 74 68 65 20 73 74 72 75 63 74 75 72 65 20 f the structure
4acc0 61 72 65 20 63 6f 70 69 65 64 20 74 6f 20 61 6e are copied to an
4acd0 20 69 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 72 internal buffer
4ace0 20 62 79 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 by sqlite.** wi
4acf0 74 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f thin the call to
4ad00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
4ad10 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e ]..**.** The xIn
4ad20 69 74 28 29 20 6d 65 74 68 6f 64 20 69 73 20 63 it() method is c
4ad30 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 alled once for e
4ad40 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ach call to [sql
4ad50 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
4ad60 29 5d 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f )].** (usually o
4ad70 6e 6c 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 nly once during
4ad80 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 the lifetime of
4ad90 74 68 65 20 70 72 6f 63 65 73 73 29 2e 20 49 74 the process). It
4ada0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 is passed.** a
4adb0 63 6f 70 79 20 6f 66 20 74 68 65 20 73 71 6c 69 copy of the sqli
4adc0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
4add0 64 73 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 49 ds.pArg value. I
4ade0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f t can be used to
4adf0 20 73 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 set.** up globa
4ae00 6c 20 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 l structures and
4ae10 20 6d 75 74 65 78 65 73 20 72 65 71 75 69 72 65 mutexes require
4ae20 64 20 62 79 20 74 68 65 20 63 75 73 74 6f 6d 20 d by the custom
4ae30 70 61 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 page cache .** i
4ae40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 mplementation. T
4ae50 68 65 20 78 53 68 75 74 64 6f 77 6e 28 29 20 6d he xShutdown() m
4ae60 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 ethod is called
4ae70 66 72 6f 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 from within .**
4ae80 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
4ae90 6e 28 29 5d 2c 20 69 66 20 74 68 65 20 61 70 70 n()], if the app
4aea0 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 lication invokes
4aeb0 20 74 68 69 73 20 41 50 49 2e 20 49 74 20 63 61 this API. It ca
4aec0 6e 20 62 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 n be used.** to
4aed0 63 6c 65 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 clean up any out
4aee0 73 74 61 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 standing resourc
4aef0 65 73 20 62 65 66 6f 72 65 20 70 72 6f 63 65 73 es before proces
4af00 73 20 73 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 s shutdown, if r
4af10 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
4af20 68 65 20 78 43 72 65 61 74 65 28 29 20 6d 65 74 he xCreate() met
4af30 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 63 hod is used to c
4af40 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 63 onstruct a new c
4af50 61 63 68 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 ache instance. T
4af60 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 he.** first para
4af70 6d 65 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 meter, szPage, i
4af80 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 s the size in by
4af90 74 65 73 20 6f 66 20 74 68 65 20 70 61 67 65 73 tes of the pages
4afa0 20 74 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 that must.** be
4afb0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 allocated by th
4afc0 65 20 63 61 63 68 65 2e 20 73 7a 50 61 67 65 20 e cache. szPage
4afd0 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f will not be a po
4afe0 77 65 72 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a wer of two. The.
4aff0 2a 2a 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 ** second argume
4b000 6e 74 2c 20 62 50 75 72 67 65 61 62 6c 65 2c 20 nt, bPurgeable,
4b010 69 73 20 74 72 75 65 20 69 66 20 74 68 65 20 63 is true if the c
4b020 61 63 68 65 20 62 65 69 6e 67 20 63 72 65 61 74 ache being creat
4b030 65 64 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 ed will.** be us
4b040 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 ed to cache data
4b050 62 61 73 65 20 70 61 67 65 73 20 72 65 61 64 20 base pages read
4b060 66 72 6f 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 from a file stor
4b070 65 64 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a ed on disk, or.*
4b080 2a 20 66 61 6c 73 65 20 69 66 20 69 74 20 69 73 * false if it is
4b090 20 75 73 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d used for an in-
4b0a0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2e memory database.
4b0b0 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c 65 The cache imple
4b0c0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 mentation.** doe
4b0d0 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 64 6f s not have to do
4b0e0 20 61 6e 79 74 68 69 6e 67 20 73 70 65 63 69 61 anything specia
4b0f0 6c 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 76 l based on the v
4b100 61 6c 75 65 20 6f 66 20 62 50 75 72 67 65 61 62 alue of bPurgeab
4b110 6c 65 2c 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 le,.** it is pur
4b120 65 6c 79 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a ely advisory. .*
4b130 2a 0a 2a 2a 20 54 68 65 20 78 43 61 63 68 65 73 *.** The xCaches
4b140 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 ize() method may
4b150 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e be called at an
4b160 79 20 74 69 6d 65 20 62 79 20 53 51 4c 69 74 65 y time by SQLite
4b170 20 74 6f 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 to set the.** s
4b180 75 67 67 65 73 74 65 64 20 6d 61 78 69 6d 75 6d uggested maximum
4b190 20 63 61 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d cache-size (num
4b1a0 62 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 6f ber of pages sto
4b1b0 72 65 64 20 62 79 29 20 74 68 65 20 63 61 63 68 red by) the cach
4b1c0 65 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 e.** instance pa
4b1d0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
4b1e0 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 t argument. This
4b1f0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 63 6f is the value co
4b200 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a nfigured using.*
4b210 2a 20 74 68 65 20 53 51 4c 69 74 65 20 22 5b 50 * the SQLite "[P
4b220 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 RAGMA cache_size
4b230 5d 22 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 ]" command. As w
4b240 69 74 68 20 74 68 65 20 62 50 75 72 67 65 61 62 ith the bPurgeab
4b250 6c 65 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a le parameter,.**
4b260 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
4b270 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 ion is not requi
4b280 72 65 64 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 red to do anythi
4b290 6e 67 20 73 70 65 63 69 61 6c 20 77 69 74 68 20 ng special with
4b2a0 74 68 69 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 this.** value, i
4b2b0 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e t is advisory on
4b2c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 ly..**.** The xP
4b2d0 61 67 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f agecount() metho
4b2e0 64 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 d should return
4b2f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
4b300 67 65 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a ges currently.**
4b310 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 stored in the c
4b320 61 63 68 65 20 73 75 70 70 6c 69 65 64 20 61 73 ache supplied as
4b330 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a an argument..**
4b340 20 0a 2a 2a 20 54 68 65 20 78 46 65 74 63 68 28 .** The xFetch(
4b350 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 ) method is used
4b360 20 74 6f 20 66 65 74 63 68 20 61 20 70 61 67 65 to fetch a page
4b370 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f and return a po
4b380 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a inter to it. .**
4b390 20 41 20 27 70 61 67 65 27 2c 20 69 6e 20 74 68 A 'page', in th
4b3a0 69 73 20 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 is context, is a
4b3b0 20 62 75 66 66 65 72 20 6f 66 20 73 7a 50 61 67 buffer of szPag
4b3c0 65 20 62 79 74 65 73 20 61 6c 69 67 6e 65 64 20 e bytes aligned
4b3d0 61 74 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 at an.** 8-byte
4b3e0 62 6f 75 6e 64 61 72 79 2e 20 54 68 65 20 70 61 boundary. The pa
4b3f0 67 65 20 74 6f 20 62 65 20 66 65 74 63 68 65 64 ge to be fetched
4b400 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 is determined b
4b410 79 20 74 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a y the key. The.*
4b420 2a 20 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 * mimimum key va
4b430 6c 75 65 20 69 73 20 31 2e 20 41 66 74 65 72 20 lue is 1. After
4b440 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 74 72 it has been retr
4b450 69 65 76 65 64 20 75 73 69 6e 67 20 78 46 65 74 ieved using xFet
4b460 63 68 2c 20 74 68 65 20 70 61 67 65 20 0a 2a 2a ch, the page .**
4b470 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 is considered t
4b480 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a o be pinned..**.
4b490 2a 2a 20 49 66 20 74 68 65 20 72 65 71 75 65 73 ** If the reques
4b4a0 74 65 64 20 70 61 67 65 20 69 73 20 61 6c 72 65 ted page is alre
4b4b0 61 64 79 20 69 6e 20 74 68 65 20 70 61 67 65 20 ady in the page
4b4c0 63 61 63 68 65 2c 20 74 68 65 6e 20 61 20 70 6f cache, then a po
4b4d0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 inter to.** the
4b4e0 63 61 63 68 65 64 20 62 75 66 66 65 72 20 73 68 cached buffer sh
4b4f0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
4b500 20 77 69 74 68 20 69 74 73 20 63 6f 6e 74 65 6e with its conten
4b510 74 73 20 69 6e 74 61 63 74 2e 20 49 66 20 74 68 ts intact. If th
4b520 65 0a 2a 2a 20 70 61 67 65 20 69 73 20 6e 6f 74 e.** page is not
4b530 20 61 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 already in the
4b540 63 61 63 68 65 2c 20 74 68 65 6e 20 74 68 65 20 cache, then the
4b550 65 78 70 65 63 74 65 64 20 62 65 68 61 76 69 6f expected behavio
4b560 75 72 20 6f 66 20 74 68 65 0a 2a 2a 20 63 61 63 ur of the.** cac
4b570 68 65 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 he is determined
4b580 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 6f 66 by the value of
4b590 20 74 68 65 20 63 72 65 61 74 65 46 6c 61 67 20 the createFlag
4b5a0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
4b5b0 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 2c 20 61 .** to xFetch, a
4b5c0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 ccording to the
4b5d0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a following table:
4b5e0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f .**.** <table bo
4b5f0 72 64 65 72 3d 31 20 77 69 64 74 68 3d 38 35 25 rder=1 width=85%
4b600 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a align=center>.*
4b610 2a 20 20 20 3c 74 72 3e 3c 74 68 3e 63 72 65 61 * <tr><th>crea
4b620 74 65 46 6c 61 67 3c 74 68 3e 45 78 70 65 63 74 teFlag<th>Expect
4b630 65 64 20 42 65 68 61 76 69 6f 75 72 0a 2a 2a 20 ed Behaviour.**
4b640 20 20 3c 74 72 3e 3c 74 64 3e 30 3c 74 64 3e 4e <tr><td>0<td>N
4b650 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 72 65 ULL should be re
4b660 74 75 72 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 63 turned. No new c
4b670 61 63 68 65 20 65 6e 74 72 79 20 69 73 20 63 72 ache entry is cr
4b680 65 61 74 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e eated..** <tr>
4b690 3c 74 64 3e 31 3c 74 64 3e 49 66 20 63 72 65 61 <td>1<td>If crea
4b6a0 74 65 46 6c 61 67 20 69 73 20 73 65 74 20 74 6f teFlag is set to
4b6b0 20 31 2c 20 74 68 69 73 20 69 6e 64 69 63 61 74 1, this indicat
4b6c0 65 73 20 74 68 61 74 20 0a 2a 2a 20 20 20 20 20 es that .**
4b6d0 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 SQLit
4b6e0 65 20 69 73 20 68 6f 6c 64 69 6e 67 20 70 69 6e e is holding pin
4b6f0 6e 65 64 20 70 61 67 65 73 20 74 68 61 74 20 63 ned pages that c
4b700 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 0a 2a an be unpinned.*
4b710 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
4b720 20 62 79 20 77 72 69 74 69 6e 67 20 74 68 65 69 by writing thei
4b730 72 20 63 6f 6e 74 65 6e 74 73 20 74 6f 20 74 68 r contents to th
4b740 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
4b750 28 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 (a.**
4b760 20 20 20 20 20 72 65 6c 61 74 69 76 65 6c 79 20 relatively
4b770 65 78 70 65 6e 73 69 76 65 20 6f 70 65 72 61 74 expensive operat
4b780 69 6f 6e 29 2e 20 49 6e 20 74 68 69 73 20 73 69 ion). In this si
4b790 74 75 61 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 20 tuation the.**
4b7a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 63 61 ca
4b7b0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
4b7c0 6f 6e 20 68 61 73 20 74 77 6f 20 63 68 6f 69 63 on has two choic
4b7d0 65 73 3a 20 69 74 20 63 61 6e 20 72 65 74 75 72 es: it can retur
4b7e0 6e 20 4e 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 20 n NULL,.**
4b7f0 20 20 20 20 20 20 20 20 20 20 69 6e 20 77 68 69 in whi
4b800 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 ch case SQLite w
4b810 69 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 75 ill attempt to u
4b820 6e 70 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 npin one or more
4b830 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 .**
4b840 20 20 20 20 70 61 67 65 73 20 62 65 66 6f 72 65 pages before
4b850 20 72 65 2d 72 65 71 75 65 73 74 69 6e 67 20 74 re-requesting t
4b860 68 65 20 73 61 6d 65 20 70 61 67 65 2c 20 6f 72 he same page, or
4b870 20 69 74 20 63 61 6e 0a 2a 2a 20 20 20 20 20 20 it can.**
4b880 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 alloca
4b890 74 65 20 61 20 6e 65 77 20 70 61 67 65 20 61 6e te a new page an
4b8a0 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 d return a point
4b8b0 65 72 20 74 6f 20 69 74 2e 20 49 66 20 61 20 6e er to it. If a n
4b8c0 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ew.**
4b8d0 20 20 20 20 20 70 61 67 65 20 69 73 20 61 6c 6c page is all
4b8e0 6f 63 61 74 65 64 2c 20 74 68 65 6e 20 69 74 20 ocated, then it
4b8f0 6d 75 73 74 20 62 65 20 63 6f 6d 70 6c 65 74 65 must be complete
4b900 6c 79 20 7a 65 72 6f 65 64 20 62 65 66 6f 72 65 ly zeroed before
4b910 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 .**
4b920 20 20 20 20 69 74 20 69 73 20 72 65 74 75 72 6e it is return
4b930 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64 ed..** <tr><td
4b940 3e 32 3c 74 64 3e 49 66 20 63 72 65 61 74 65 46 >2<td>If createF
4b950 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 32 2c lag is set to 2,
4b960 20 74 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 then SQLite is
4b970 6e 6f 74 20 68 6f 6c 64 69 6e 67 20 61 6e 79 0a not holding any.
4b980 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
4b990 20 20 70 69 6e 6e 65 64 20 70 61 67 65 73 20 61 pinned pages a
4b9a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
4b9b0 68 65 20 73 70 65 63 69 66 69 63 20 63 61 63 68 he specific cach
4b9c0 65 20 70 61 73 73 65 64 0a 2a 2a 20 20 20 20 20 e passed.**
4b9d0 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 as th
4b9e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
4b9f0 20 74 6f 20 78 46 65 74 63 68 28 29 20 74 68 61 to xFetch() tha
4ba00 74 20 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 t can be unpinne
4ba10 64 2e 20 54 68 65 0a 2a 2a 20 20 20 20 20 20 20 d. The.**
4ba20 20 20 20 20 20 20 20 20 20 63 61 63 68 65 20 69 cache i
4ba30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
4ba40 6f 75 6c 64 20 61 74 74 65 6d 70 74 20 74 6f 20 ould attempt to
4ba50 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 0a 2a allocate a new.*
4ba60 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
4ba70 20 63 61 63 68 65 20 65 6e 74 72 79 20 61 6e 64 cache entry and
4ba80 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 return a pointe
4ba90 72 20 74 6f 20 69 74 2e 20 41 67 61 69 6e 2c 20 r to it. Again,
4baa0 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 the new.**
4bab0 20 20 20 20 20 20 20 20 20 20 70 61 67 65 20 73 page s
4bac0 68 6f 75 6c 64 20 62 65 20 7a 65 72 6f 65 64 20 hould be zeroed
4bad0 62 65 66 6f 72 65 20 69 74 20 69 73 20 72 65 74 before it is ret
4bae0 75 72 6e 65 64 2e 20 49 66 20 74 68 65 20 78 46 urned. If the xF
4baf0 65 74 63 68 28 29 0a 2a 2a 20 20 20 20 20 20 20 etch().**
4bb00 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 method
4bb10 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 77 68 65 returns NULL whe
4bb20 6e 20 63 72 65 61 74 65 46 6c 61 67 3d 3d 32 2c n createFlag==2,
4bb30 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
4bb40 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 that.**
4bb50 20 20 20 20 20 20 20 61 20 6d 65 6d 6f 72 79 20 a memory
4bb60 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 allocation faile
4bb70 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 53 51 d and returns SQ
4bb80 4c 49 54 45 5f 4e 4f 4d 45 4d 20 74 6f 20 74 68 LITE_NOMEM to th
4bb90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 e.**
4bba0 20 20 20 20 75 73 65 72 2e 0a 2a 2a 20 3c 2f 74 user..** </t
4bbb0 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 78 55 6e 70 able>.**.** xUnp
4bbc0 69 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 in() is called b
4bbd0 79 20 53 51 4c 69 74 65 20 77 69 74 68 20 61 20 y SQLite with a
4bbe0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 75 72 pointer to a cur
4bbf0 72 65 6e 74 6c 79 20 70 69 6e 6e 65 64 20 70 61 rently pinned pa
4bc00 67 65 0a 2a 2a 20 61 73 20 69 74 73 20 73 65 63 ge.** as its sec
4bc10 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 ond argument. If
4bc20 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
4bc30 65 74 65 72 2c 20 64 69 73 63 61 72 64 2c 20 69 eter, discard, i
4bc40 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 s non-zero,.** t
4bc50 68 65 6e 20 74 68 65 20 70 61 67 65 20 73 68 6f hen the page sho
4bc60 75 6c 64 20 62 65 20 65 76 69 63 74 65 64 20 66 uld be evicted f
4bc70 72 6f 6d 20 74 68 65 20 63 61 63 68 65 2e 20 49 rom the cache. I
4bc80 6e 20 74 68 69 73 20 63 61 73 65 20 53 51 4c 69 n this case SQLi
4bc90 74 65 20 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 te .** assumes t
4bca0 68 61 74 20 74 68 65 20 6e 65 78 74 20 74 69 6d hat the next tim
4bcb0 65 20 74 68 65 20 70 61 67 65 20 69 73 20 72 65 e the page is re
4bcc0 74 72 69 65 76 65 64 20 66 72 6f 6d 20 74 68 65 trieved from the
4bcd0 20 63 61 63 68 65 20 75 73 69 6e 67 0a 2a 2a 20 cache using.**
4bce0 74 68 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 the xFetch() met
4bcf0 68 6f 64 2c 20 69 74 20 77 69 6c 6c 20 62 65 20 hod, it will be
4bd00 7a 65 72 6f 65 64 2e 20 49 66 20 74 68 65 20 64 zeroed. If the d
4bd10 69 73 63 61 72 64 20 70 61 72 61 6d 65 74 65 72 iscard parameter
4bd20 20 69 73 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 65 is.** zero, the
4bd30 6e 20 74 68 65 20 70 61 67 65 20 69 73 20 63 6f n the page is co
4bd40 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 75 nsidered to be u
4bd50 6e 70 69 6e 6e 65 64 2e 20 54 68 65 20 63 61 63 npinned. The cac
4bd60 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
4bd70 6e 0a 2a 2a 20 6d 61 79 20 63 68 6f 6f 73 65 20 n.** may choose
4bd80 74 6f 20 72 65 63 6c 61 69 6d 20 28 66 72 65 65 to reclaim (free
4bd90 20 6f 72 20 72 65 63 79 63 6c 65 29 20 75 6e 70 or recycle) unp
4bda0 69 6e 6e 65 64 20 70 61 67 65 73 20 61 74 20 61 inned pages at a
4bdb0 6e 79 20 74 69 6d 65 2e 0a 2a 2a 20 53 51 4c 69 ny time..** SQLi
4bdc0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
4bdd0 6e 65 78 74 20 74 69 6d 65 20 74 68 65 20 70 61 next time the pa
4bde0 67 65 20 69 73 20 72 65 74 72 69 65 76 65 64 20 ge is retrieved
4bdf0 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 0a 2a from the cache.*
4be00 2a 20 69 74 20 77 69 6c 6c 20 65 69 74 68 65 72 * it will either
4be10 20 62 65 20 7a 65 72 6f 65 64 2c 20 6f 72 20 63 be zeroed, or c
4be20 6f 6e 74 61 69 6e 20 74 68 65 20 73 61 6d 65 20 ontain the same
4be30 64 61 74 61 20 74 68 61 74 20 69 74 20 64 69 64 data that it did
4be40 20 77 68 65 6e 20 69 74 0a 2a 2a 20 77 61 73 20 when it.** was
4be50 75 6e 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 unpinned..**.**
4be60 54 68 65 20 63 61 63 68 65 20 69 73 20 6e 6f 74 The cache is not
4be70 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 65 72 required to per
4be80 66 6f 72 6d 20 61 6e 79 20 72 65 66 65 72 65 6e form any referen
4be90 63 65 20 63 6f 75 6e 74 69 6e 67 2e 20 41 20 73 ce counting. A s
4bea0 69 6e 67 6c 65 20 0a 2a 2a 20 63 61 6c 6c 20 74 ingle .** call t
4beb0 6f 20 78 55 6e 70 69 6e 28 29 20 75 6e 70 69 6e o xUnpin() unpin
4bec0 73 20 74 68 65 20 70 61 67 65 20 72 65 67 61 72 s the page regar
4bed0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d dless of the num
4bee0 62 65 72 20 6f 66 20 70 72 69 6f 72 20 63 61 6c ber of prior cal
4bef0 6c 73 20 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 ls .** to xFetch
4bf00 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 ()..**.** The xR
4bf10 65 6b 65 79 28 29 20 6d 65 74 68 6f 64 20 69 73 ekey() method is
4bf20 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 used to change
4bf30 74 68 65 20 6b 65 79 20 76 61 6c 75 65 20 61 73 the key value as
4bf40 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
4bf50 65 0a 2a 2a 20 70 61 67 65 20 70 61 73 73 65 64 e.** page passed
4bf60 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
4bf70 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 6f 6c 64 rgument from old
4bf80 4b 65 79 20 74 6f 20 6e 65 77 4b 65 79 2e 20 49 Key to newKey. I
4bf90 66 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 70 f the cache.** p
4bfa0 72 65 76 69 6f 75 73 6c 79 20 63 6f 6e 74 61 69 reviously contai
4bfb0 6e 73 20 61 6e 20 65 6e 74 72 79 20 61 73 73 6f ns an entry asso
4bfc0 63 69 61 74 65 64 20 77 69 74 68 20 6e 65 77 4b ciated with newK
4bfd0 65 79 2c 20 69 74 20 73 68 6f 75 6c 64 20 62 65 ey, it should be
4bfe0 0a 2a 2a 20 64 69 73 63 61 72 64 65 64 2e 20 41 .** discarded. A
4bff0 6e 79 20 70 72 69 6f 72 20 63 61 63 68 65 20 65 ny prior cache e
4c000 6e 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 ntry associated
4c010 77 69 74 68 20 6e 65 77 4b 65 79 20 69 73 20 67 with newKey is g
4c020 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a uaranteed not.**
4c030 20 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a to be pinned..*
4c040 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 *.** When SQLite
4c050 20 63 61 6c 6c 73 20 74 68 65 20 78 54 72 75 6e calls the xTrun
4c060 63 61 74 65 28 29 20 6d 65 74 68 6f 64 2c 20 74 cate() method, t
4c070 68 65 20 63 61 63 68 65 20 6d 75 73 74 20 64 69 he cache must di
4c080 73 63 61 72 64 20 61 6c 6c 0a 2a 2a 20 65 78 69 scard all.** exi
4c090 73 74 69 6e 67 20 63 61 63 68 65 20 65 6e 74 72 sting cache entr
4c0a0 69 65 73 20 77 69 74 68 20 70 61 67 65 20 6e 75 ies with page nu
4c0b0 6d 62 65 72 73 20 28 6b 65 79 73 29 20 67 72 65 mbers (keys) gre
4c0c0 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 ater than or equ
4c0d0 61 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 76 61 6c al.** to the val
4c0e0 75 65 20 6f 66 20 74 68 65 20 69 4c 69 6d 69 74 ue of the iLimit
4c0f0 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
4c100 64 20 74 6f 20 78 54 72 75 6e 63 61 74 65 28 29 d to xTruncate()
4c110 2e 20 49 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 . If any.** of t
4c120 68 65 73 65 20 70 61 67 65 73 20 61 72 65 20 70 hese pages are p
4c130 69 6e 6e 65 64 2c 20 74 68 65 79 20 61 72 65 20 inned, they are
4c140 69 6d 70 6c 69 63 69 74 6c 79 20 75 6e 70 69 6e implicitly unpin
4c150 6e 65 64 2c 20 6d 65 61 6e 69 6e 67 20 74 68 61 ned, meaning tha
4c160 74 0a 2a 2a 20 74 68 65 79 20 63 61 6e 20 62 65 t.** they can be
4c170 20 73 61 66 65 6c 79 20 64 69 73 63 61 72 64 65 safely discarde
4c180 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 d..**.** The xDe
4c190 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 20 69 stroy() method i
4c1a0 73 20 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65 s used to delete
4c1b0 20 61 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 a cache allocat
4c1c0 65 64 20 62 79 20 78 43 72 65 61 74 65 28 29 2e ed by xCreate().
4c1d0 0a 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 72 63 65 .** All resource
4c1e0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
4c1f0 68 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 h the specified
4c200 63 61 63 68 65 20 73 68 6f 75 6c 64 20 62 65 20 cache should be
4c210 66 72 65 65 64 2e 20 41 66 74 65 72 0a 2a 2a 20 freed. After.**
4c220 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 44 65 73 calling the xDes
4c230 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 2c 20 53 troy() method, S
4c240 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 72 73 20 QLite considers
4c250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 the [sqlite3_pca
4c260 63 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 20 che*].** handle
4c270 69 6e 76 61 6c 69 64 2c 20 61 6e 64 20 77 69 6c invalid, and wil
4c280 6c 20 6e 6f 74 20 75 73 65 20 69 74 20 77 69 74 l not use it wit
4c290 68 20 61 6e 79 20 6f 74 68 65 72 20 73 71 6c 69 h any other sqli
4c2a0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
4c2b0 64 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e ds.** functions.
4c2c0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
4c2d0 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 ct sqlite3_pcach
4c2e0 65 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 e_methods sqlite
4c2f0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
4c300 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
4c310 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 _pcache_methods
4c320 7b 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 3b 0a {. void *pArg;.
4c330 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 int (*xInit)(v
4c340 6f 69 64 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a oid*);. void (*
4c350 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a xShutdown)(void*
4c360 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 70 63 61 );. sqlite3_pca
4c370 63 68 65 20 2a 28 2a 78 43 72 65 61 74 65 29 28 che *(*xCreate)(
4c380 69 6e 74 20 73 7a 50 61 67 65 2c 20 69 6e 74 20 int szPage, int
4c390 62 50 75 72 67 65 61 62 6c 65 29 3b 0a 20 20 76 bPurgeable);. v
4c3a0 6f 69 64 20 28 2a 78 43 61 63 68 65 73 69 7a 65 oid (*xCachesize
4c3b0 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 )(sqlite3_pcache
4c3c0 2a 2c 20 69 6e 74 20 6e 43 61 63 68 65 73 69 7a *, int nCachesiz
4c3d0 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 50 61 67 e);. int (*xPag
4c3e0 65 63 6f 75 6e 74 29 28 73 71 6c 69 74 65 33 5f ecount)(sqlite3_
4c3f0 70 63 61 63 68 65 2a 29 3b 0a 20 20 76 6f 69 64 pcache*);. void
4c400 20 2a 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 *(*xFetch)(sqli
4c410 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 te3_pcache*, uns
4c420 69 67 6e 65 64 20 6b 65 79 2c 20 69 6e 74 20 63 igned key, int c
4c430 72 65 61 74 65 46 6c 61 67 29 3b 0a 20 20 76 6f reateFlag);. vo
4c440 69 64 20 28 2a 78 55 6e 70 69 6e 29 28 73 71 6c id (*xUnpin)(sql
4c450 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f ite3_pcache*, vo
4c460 69 64 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 64 id*, int discard
4c470 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 6b );. void (*xRek
4c480 65 79 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 ey)(sqlite3_pcac
4c490 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 69 he*, void*, unsi
4c4a0 67 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 75 6e 73 gned oldKey, uns
4c4b0 69 67 6e 65 64 20 6e 65 77 4b 65 79 29 3b 0a 20 igned newKey);.
4c4c0 20 76 6f 69 64 20 28 2a 78 54 72 75 6e 63 61 74 void (*xTruncat
4c4d0 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e)(sqlite3_pcach
4c4e0 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 69 4c 69 e*, unsigned iLi
4c4f0 6d 69 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 mit);. void (*x
4c500 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 Destroy)(sqlite3
4c510 5f 70 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 2f _pcache*);.};../
4c520 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 *.** Undo the ha
4c530 63 6b 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 ck that converts
4c540 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
4c550 74 79 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 types to integer
4c560 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f for.** builds o
4c570 6e 20 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 n processors wit
4c580 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f hout floating po
4c590 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a int support..*/.
4c5a0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
4c5b0 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
4c5c0 54 0a 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 T.# undef double
4c5d0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 .#endif..#ifdef
4c5e0 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f __cplusplus.} /
4c5f0 2a 20 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 * End of the 'ex
4c600 74 65 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 tern "C"' block
4c610 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 */.#endif.#endif
4c620 0a .