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 31 35 20 32 30 30 38 2f 31 n,v 1.415 2008/1
05f0: 31 2f 31 39 20 30 31 3a 32 30 3a 32 36 20 64 72 1/19 01:20:26 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 36 2e 31 22 0a 23 "3.6.6.1".#
1020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
1030: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 33 30 RSION_NUMBER 30
1040: 30 36 30 30 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 06006../*.** CAP
1050: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
1060: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 Library Version
1070: 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d Numbers {H10020}
1080: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 <S60100>.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 ersion.**.** The
10b0: 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76 se features prov
10c0: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 ide the same inf
10d0: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 ormation as the
10e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
10f0: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f .** and [SQLITE_
1100: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 VERSION_NUMBER]
1110: 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 #defines in the
1120: 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20 header, but are
1130: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 associated.** wi
1140: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 th the library i
1150: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 nstead of the he
1160: 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 ader file. Caut
1170: 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 ious programmers
1180: 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 might.** includ
1190: 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65 e a check in the
11a0: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ir application t
11b0: 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a o verify that.**
11c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
11d0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 ion_number() alw
11e0: 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 ays returns the
11f0: 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 value.** [SQLITE
1200: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d _VERSION_NUMBER]
1210: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1220: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
1230: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
1240: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 s the same infor
1250: 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 mation as is.**
1260: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
1270: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 ersion[] string
1280: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 constant. The f
1290: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 unction is provi
12a0: 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 ded.** for use i
12b0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
12c0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
12d0: 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63 o not have direc
12e0: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 t access to stri
12f0: 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 ng.** constants
1300: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a within the DLL..
1310: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
1320: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d :.**.** {H10021}
1330: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 The [sqlite3_li
1340: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
1350: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 )] interface sha
1360: 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 ll return.**
1370: 20 20 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72 an integer
1380: 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 equal to [SQLIT
1390: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
13a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 ]..**.** {H10022
13b0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
13c0: 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 ersion] string c
13d0: 6f 6e 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f onstant shall co
13e0: 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ntain.**
13f0: 20 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 the text of th
1400: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f e [SQLITE_VERSIO
1410: 4e 5d 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a N] string..**.**
1420: 20 7b 48 31 30 30 32 33 7d 20 54 68 65 20 5b 73 {H10023} The [s
1430: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1440: 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 n()] function sh
1450: 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 all return.**
1460: 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 a pointer
1470: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1480: 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 _version] string
1490: 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 constant..*/.SQ
14a0: 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 LITE_EXTERN cons
14b0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 t char sqlite3_v
14c0: 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 ersion[];.const
14d0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 char *sqlite3_li
14e0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a bversion(void);.
14f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 int sqlite3_libv
1500: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f ersion_number(vo
1510: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 id);../*.** CAPI
1520: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 3REF: Test To Se
1530: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 e If The Library
1540: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20 7b Is Threadsafe {
1550: 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30 3e H10100} <S60100>
1560: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 .**.** SQLite ca
1570: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 n be compiled wi
1580: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 th or without mu
1590: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 texes. When.**
15a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
15b0: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f ADSAFE] C prepro
15c0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 31 20 6f cessor macro 1 o
15d0: 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 r 2, mutexes.**
15e0: 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 are enabled and
15f0: 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 SQLite is thread
1600: 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a safe. When the.
1610: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 ** [SQLITE_THREA
1620: 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 DSAFE] macro is
1630: 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 0, .** the mutex
1640: 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 es are omitted.
1650: 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 Without the mut
1660: 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 exes, it is not
1670: 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 safe.** to use S
1680: 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 QLite concurrent
1690: 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 ly from more tha
16a0: 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a n one thread..**
16b0: 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 .** Enabling mut
16c0: 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 exes incurs a me
16d0: 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d asurable perform
16e0: 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a ance penalty..**
16f0: 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 So if speed is
1700: 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 of utmost import
1710: 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 ance, it makes s
1720: 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a ense to disable.
1730: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 ** the mutexes.
1740: 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d But for maximum
1750: 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 safety, mutexes
1760: 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c should be enabl
1770: 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 ed..** The defau
1780: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 lt behavior is f
1790: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 or mutexes to be
17a0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
17b0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
17c0: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 20 an be used by a
17d0: 70 72 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 program to make
17e0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a sure that the.**
17f0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 version of SQLi
1800: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 te that it is li
1810: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 nking against wa
1820: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
1830: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 ** the desired s
1840: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 etting of the [S
1850: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1860: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 ] macro..**.** T
1870: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e his interface on
1880: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 ly reports on th
1890: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d e compile-time m
18a0: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 utex setting.**
18b0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
18c0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e HREADSAFE] flag.
18d0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 If SQLite is c
18e0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
18f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1900: 45 3d 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 E=1 then mutexes
1910: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 are enabled by
1920: 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 default but.** c
1930: 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 an be fully or p
1940: 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 artially disable
1950: 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 d using a call t
1960: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
1970: 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 g()].** with the
1980: 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 verbs [SQLITE_C
1990: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
19a0: 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e AD], [SQLITE_CON
19b0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
19c0: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
19d0: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 CONFIG_MUTEX].
19e0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
19f0: 20 6f 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f of this functio
1a00: 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 n shows.** only
1a10: 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 the default comp
1a20: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 ile-time setting
1a30: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 , not any run-ti
1a40: 6d 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f me changes.** to
1a50: 20 74 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a that setting..*
1a60: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 *.** See the [th
1a70: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f reading mode] do
1a80: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
1a90: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
1aa0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e mation..**.** IN
1ab0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
1ac0: 7b 48 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 {H10101} The [sq
1ad0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1ae0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 ()] function sha
1af0: 6c 6c 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 69 ll return zero i
1b00: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e f.** an
1b10: 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c 69 74 65 d only if SQLite
1b20: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
1b30: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 th mutexing code
1b40: 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 omitted..**.**
1b50: 7b 48 31 30 31 30 32 7d 20 54 68 65 20 76 61 6c {H10102} The val
1b60: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
1b70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 he [sqlite3_thre
1b80: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 adsafe()] functi
1b90: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 on.** s
1ba0: 68 61 6c 6c 20 72 65 6d 61 69 6e 20 74 68 65 20 hall remain the
1bb0: 73 61 6d 65 20 61 63 72 6f 73 73 20 63 61 6c 6c same across call
1bc0: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f s to [sqlite3_co
1bd0: 6e 66 69 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 nfig()]..*/.int
1be0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
1bf0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a fe(void);../*.**
1c00: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
1c10: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 ase Connection H
1c20: 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c andle {H12000} <
1c30: 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S40200>.** KEYWO
1c40: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 RDS: {database c
1c50: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 onnection} {data
1c60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
1c70: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 }.**.** Each ope
1c80: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
1c90: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 e is represented
1ca0: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f by a pointer to
1cb0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a an instance of.
1cc0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 ** the opaque st
1cd0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 ructure named "s
1ce0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 qlite3". It is
1cf0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 useful to think
1d00: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a of an sqlite3.**
1d10: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f pointer as an o
1d20: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c bject. The [sql
1d30: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
1d40: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1d50: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
1d60: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 3_open_v2()] int
1d70: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 erfaces are its
1d80: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e constructors, an
1d90: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
1da0: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 ()].** is its de
1db0: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 structor. There
1dc0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 are many other
1dd0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 interfaces (such
1de0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f as.** [sqlite3_
1df0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
1e00: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
1e10: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a unction()], and.
1e20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ** [sqlite3_busy
1e30: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e _timeout()] to n
1e40: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 ame but three) t
1e50: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 hat are methods
1e60: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 on an.** sqlite3
1e70: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 object..*/.type
1e80: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
1e90: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a e3 sqlite3;../*.
1ea0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d ** CAPI3REF: 64-
1eb0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 Bit Integer Type
1ec0: 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 s {H10200} <S101
1ed0: 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 10>.** KEYWORDS:
1ee0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 sqlite_int64 sq
1ef0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a lite_uint64.**.*
1f00: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 * Because there
1f10: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 is no cross-plat
1f20: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 form way to spec
1f30: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 ify 64-bit integ
1f40: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 er types.** SQLi
1f50: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 te includes type
1f60: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 defs for 64-bit
1f70: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 signed and unsig
1f80: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a ned integers..**
1f90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1fa0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
1fb0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 3_uint64 are the
1fc0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 preferred type
1fd0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 definitions..**
1fe0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 The sqlite_int64
1ff0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
2000: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 64 types are sup
2010: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 ported for backw
2020: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ards.** compatib
2030: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a ility only..**.*
2040: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
2050: 0a 2a 2a 20 7b 48 31 30 32 30 31 7d 20 54 68 65 .** {H10201} The
2060: 20 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 [sqlite_int64]
2070: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 and [sqlite3_int
2080: 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 64] type shall s
2090: 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 pecify.**
20a0: 20 20 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e a 64-bit sign
20b0: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a ed integer..**.*
20c0: 2a 20 7b 48 31 30 32 30 32 7d 20 54 68 65 20 5b * {H10202} The [
20d0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 sqlite_uint64] a
20e0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 nd [sqlite3_uint
20f0: 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 64] type shall s
2100: 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 pecify.**
2110: 20 20 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 a 64-bit unsi
2120: 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f gned integer..*/
2130: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 .#ifdef SQLITE_I
2140: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 NT64_TYPE. type
2150: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
2160: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 _TYPE sqlite_int
2170: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
2180: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e signed SQLITE_IN
2190: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
21a0: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 uint64;.#elif de
21b0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
21c0: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 || defined(__BOR
21d0: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 LANDC__). typed
21e0: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ef __int64 sqlit
21f0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
2200: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e ef unsigned __in
2210: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 t64 sqlite_uint6
2220: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 4;.#else. typed
2230: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ef long long int
2240: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2250: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2260: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 d long long int
2270: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
2280: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 endif.typedef sq
2290: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
22a0: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 e3_int64;.typede
22b0: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 f sqlite_uint64
22c0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a sqlite3_uint64;.
22d0: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c ./*.** If compil
22e0: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 ing for a proces
22f0: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 sor that lacks f
2300: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 loating point su
2310: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 pport,.** substi
2320: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 tute integer for
2330: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e floating-point.
2340: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
2350: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
2360: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 POINT.# define d
2370: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e ouble sqlite3_in
2380: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a t64.#endif../*.*
2390: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
23a0: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 ing A Database C
23b0: 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 onnection {H1201
23c0: 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 0} <S30100><S402
23d0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
23e0: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 outine is the de
23f0: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 structor for the
2400: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
2410: 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 t..**.** Applica
2420: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 tions should [sq
2430: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
2440: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b finalize] all [
2450: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2460: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c nts].** and [sql
2470: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
2480: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c | close] all [BL
2490: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f OB handles] asso
24a0: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 ciated with.** t
24b0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
24c0: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 ect prior to att
24d0: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 empting to close
24e0: 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 the object..**
24f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 The [sqlite3_nex
2500: 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 t_stmt()] interf
2510: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
2520: 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a to locate all.**
2530: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2540: 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 ments] associate
2550: 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
2560: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
2570: 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 f desired..** Ty
2580: 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 pical code might
2590: 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a look like this:
25a0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
25b0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 te><pre>.** sqli
25c0: 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b te3_stmt *pStmt;
25d0: 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d .** while( (pStm
25e0: 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 t = sqlite3_next
25f0: 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 _stmt(db, 0))!=0
2600: 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 ){.**
2610: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2620: 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a (pStmt);.** }.**
2630: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
2640: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 ote>.**.** If [s
2650: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
2660: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 is invoked while
2670: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
2680: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 s open,.** the t
2690: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 ransaction is au
26a0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
26b0: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 ed back..**.** I
26c0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
26d0: 20 7b 48 31 32 30 31 31 7d 20 41 20 73 75 63 63 {H12011} A succ
26e0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
26f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
2700: 5d 20 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 ] shall destroy
2710: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2720: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2730: 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a tion] object C..
2740: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 **.** {H12012} A
2750: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
2760: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
2770: 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 se(C)] shall ret
2780: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a urn SQLITE_OK..*
2790: 2a 0a 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 *.** {H12013} A
27a0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
27b0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to [sqlite3_clos
27c0: 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 e(C)] shall rele
27d0: 61 73 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 ase all.**
27e0: 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 memory and s
27f0: 79 73 74 65 6d 20 72 65 73 6f 75 72 63 65 73 20 ystem resources
2800: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2810: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2820: 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 tion].**
2830: 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 C..**.** {H120
2840: 31 34 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 14} A call to [s
2850: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d qlite3_close(C)]
2860: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 on a [database
2870: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 connection] C th
2880: 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 at.** h
2890: 61 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f as one or more o
28a0: 70 65 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 pen [prepared st
28b0: 61 74 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 atements] shall
28c0: 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 fail with.**
28d0: 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 an [SQLITE
28e0: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 _BUSY] error cod
28f0: 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 e..**.** {H12015
2900: 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c } A call to [sql
2910: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 ite3_close(C)] w
2920: 68 65 72 65 20 43 20 69 73 20 61 20 4e 55 4c 4c here C is a NULL
2930: 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a pointer shall.*
2940: 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 61 20 * be a
2950: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 harmless no-op r
2960: 65 74 75 72 6e 69 6e 67 20 53 51 4c 49 54 45 5f eturning SQLITE_
2970: 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 OK..**.** {H1201
2980: 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 9} When [sqlite3
2990: 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73 20 69 6e _close(C)] is in
29a0: 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 voked on a [data
29b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
29c0: 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 C.** t
29d0: 68 61 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e hat has a pendin
29e0: 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 g transaction, t
29f0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 he transaction s
2a00: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 hall be.**
2a10: 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e rolled back.
2a20: 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f .**.** ASSUMPTIO
2a30: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 NS:.**.** {A1201
2a40: 36 7d 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 6} The C paramet
2a50: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 er to [sqlite3_c
2a60: 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 lose(C)] must be
2a70: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a either a NULL.*
2a80: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 * point
2a90: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 er or an [sqlite
2aa0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 3] object pointe
2ab0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 r obtained.**
2ac0: 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c from [sql
2ad0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
2ae0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
2af0: 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 , or.**
2b00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
2b10: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 2()], and not pr
2b20: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e eviously closed.
2b30: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2b40: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 close(sqlite3 *)
2b50: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 ;../*.** The typ
2b60: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b e for a callback
2b70: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 function..** Th
2b80: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 is is legacy and
2b90: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 deprecated. It
2ba0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 is included for
2bb0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 historical.** c
2bc0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 ompatibility and
2bd0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 is not document
2be0: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 ed..*/.typedef i
2bf0: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c nt (*sqlite3_cal
2c00: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 lback)(void*,int
2c10: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 ,char**, char**)
2c20: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2c30: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 F: One-Step Quer
2c40: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 y Execution Inte
2c50: 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c rface {H12100} <
2c60: 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S10000>.**.** Th
2c70: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
2c80: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 interface is a
2c90: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f convenient way o
2ca0: 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 f running one or
2cb0: 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 more.** SQL sta
2cc0: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 tements without
2cd0: 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 having to write
2ce0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e a lot of C code.
2cf0: 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f The UTF-8 enco
2d00: 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ded.** SQL state
2d10: 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 ments are passed
2d20: 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e in as the secon
2d30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
2d40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a qlite3_exec()..*
2d50: 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 * The statements
2d60: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f are evaluated o
2d70: 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 ne by one until
2d80: 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 either an error
2d90: 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 or.** an interru
2da0: 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 pt is encountere
2db0: 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 d, or until they
2dc0: 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 are all done.
2dd0: 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 The 3rd paramete
2de0: 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f r.** is an optio
2df0: 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 nal callback tha
2e00: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 t is invoked onc
2e10: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f e for each row o
2e20: 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 f any query.** r
2e30: 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 esults produced
2e40: 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 by the SQL state
2e50: 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 ments. The 5th
2e60: 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 parameter tells
2e70: 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 where.** to writ
2e80: 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 e any error mess
2e90: 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ages..**.** The
2ea0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 error message pa
2eb0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 ssed back throug
2ec0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 h the 5th parame
2ed0: 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 ter is held.** i
2ee0: 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 n memory obtaine
2ef0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2f00: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 malloc()]. To a
2f10: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 void a memory le
2f20: 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 ak,.** the calli
2f30: 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 ng application s
2f40: 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 hould call [sqli
2f50: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 te3_free()] on a
2f60: 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 ny error.** mess
2f70: 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 age returned thr
2f80: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 ough the 5th par
2f90: 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 ameter when it h
2fa0: 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e as finished usin
2fb0: 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d g.** the error m
2fc0: 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 essage..**.** If
2fd0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2fe0: 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 nt in the 2nd pa
2ff0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 rameter is NULL
3000: 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 or an empty stri
3010: 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e ng.** or a strin
3020: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c g containing onl
3030: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 y whitespace and
3040: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 comments, then
3050: 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d no SQL.** statem
3060: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 ents are evaluat
3070: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 ed and the datab
3080: 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 ase is not chang
3090: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
30a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
30b0: 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d erface is implem
30c0: 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f ented in terms o
30d0: 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 f.** [sqlite3_pr
30e0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
30f0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 lite3_step()], a
3100: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 nd [sqlite3_fina
3110: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lize()]..** The
3120: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 sqlite3_exec() r
3130: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 outine does noth
3140: 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 ing to the datab
3150: 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 ase that cannot
3160: 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 be done.** by [s
3170: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
3180: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 2()], [sqlite3_s
3190: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c tep()], and [sql
31a0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
31b0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
31c0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 TS:.**.** {H1210
31d0: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 1} A successful
31e0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
31f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c qlite3_exec(D,S,
3200: 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 C,A,E)].**
3210: 20 20 20 20 73 68 61 6c 6c 20 73 65 71 75 65 6e shall sequen
3220: 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20 tially evaluate
3230: 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38 all of the UTF-8
3240: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 encoded,.**
3250: 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d semicolon-
3260: 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 separated SQL st
3270: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 atements in the
3280: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
3290: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 ** stri
32a0: 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68 65 20 ng S within the
32b0: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b context of the [
32c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
32d0: 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ion] D..**.** {H
32e0: 31 32 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 12102} If the S
32f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
3300: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 lite3_exec(D,S,C
3310: 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 ,A,E)] is NULL t
3320: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
3330: 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 the actions of t
3340: 68 65 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 he interface sha
3350: 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 ll be the same a
3360: 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 s if the.**
3370: 20 20 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 S parameter
3380: 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 were an empty s
3390: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tring..**.** {H1
33a0: 32 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 2104} The return
33b0: 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 value of [sqlit
33c0: 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c e3_exec()] shall
33d0: 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 be [SQLITE_OK]
33e0: 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 if all.**
33f0: 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 SQL statement
3400: 73 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c s run successful
3410: 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 ly and to comple
3420: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 tion..**.** {H12
3430: 31 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 105} The return
3440: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 value of [sqlite
3450: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 3_exec()] shall
3460: 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 be an appropriat
3470: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f e.** no
3480: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
3490: 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 de] if any SQL s
34a0: 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a tatement fails..
34b0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d 20 49 **.** {H12107} I
34c0: 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 f one or more of
34d0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
34e0: 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 nts handed to [s
34f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a qlite3_exec()].*
3500: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
3510: 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 n results and th
3520: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
3530: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
3540: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
3550: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
3560: 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 ion specified by
3570: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
3580: 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 er shall be.**
3590: 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 invoked
35a0: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f once for each ro
35b0: 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a w of result..**.
35c0: 2a 2a 20 7b 48 31 32 31 31 30 7d 20 49 66 20 74 ** {H12110} If t
35d0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
35e0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 rns a non-zero v
35f0: 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 alue then [sqlit
3600: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 e3_exec()].**
3610: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f shall abo
3620: 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 rt the SQL state
3630: 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 ment it is curre
3640: 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c ntly evaluating,
3650: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 .** ski
3660: 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 p all subsequent
3670: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c SQL statements,
3680: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
3690: 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
36a0: 2a 20 7b 48 31 32 31 31 33 7d 20 54 68 65 20 5b * {H12113} The [
36b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
36c0: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 routine shall pa
36d0: 73 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d ss its 4th param
36e0: 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 eter through.**
36f0: 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 as the
3700: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 1st parameter of
3710: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
3720: 2a 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20 54 68 *.** {H12116} Th
3730: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 e [sqlite3_exec(
3740: 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c )] routine shall
3750: 20 73 65 74 20 74 68 65 20 32 6e 64 20 70 61 72 set the 2nd par
3760: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a ameter of its.**
3770: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 callba
3780: 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d ck to be the num
3790: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
37a0: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
37b0: 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 w of.**
37c0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b result..**.** {
37d0: 48 31 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c H12119} The [sql
37e0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 ite3_exec()] rou
37f0: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 tine shall set t
3800: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
3810: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 of its.**
3820: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 callback to
3830: 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 be an array of p
3840: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3850: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a gs holding the.*
3860: 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
3870: 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d s for each colum
3880: 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 n in the current
3890: 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 result set row
38a0: 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f as.** o
38b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
38c0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
38d0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 t()]..**.** {H12
38e0: 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 122} The [sqlite
38f0: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 3_exec()] routin
3900: 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 e shall set the
3910: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 4th parameter of
3920: 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 its.**
3930: 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 callback to be
3940: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
3950: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
3960: 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 holding the.**
3970: 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 names of
3980: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 result columns
3990: 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d as obtained from
39a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
39b0: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _name()]..**.**
39c0: 7b 48 31 32 31 32 35 7d 20 49 66 20 74 68 65 20 {H12125} If the
39d0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
39e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
39f0: 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a ] is NULL then.*
3a00: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
3a10: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c te3_exec()] shal
3a20: 6c 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 l silently disca
3a30: 72 64 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 rd query results
3a40: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 31 7d ..**.** {H12131}
3a50: 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 If an error occ
3a60: 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e urs while parsin
3a70: 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 g or evaluating
3a80: 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a any of the SQL.*
3a90: 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 * state
3aa0: 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70 ments in the S p
3ab0: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c arameter of [sql
3ac0: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c ite3_exec(D,S,C,
3ad0: 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 A,E)] and if.**
3ae0: 20 20 20 20 20 20 20 20 20 74 68 65 20 45 20 70 the E p
3af0: 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 arameter is not
3b00: 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 NULL, then [sqli
3b10: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c te3_exec()] shal
3b20: 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 l store.**
3b30: 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 in *E an app
3b40: 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d ropriate error m
3b50: 65 73 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 essage written i
3b60: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
3b70: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ned.**
3b80: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
3b90: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b lloc()]..**.** {
3ba0: 48 31 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c H12134} The [sql
3bb0: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c ite3_exec(D,S,C,
3bc0: 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 A,E)] routine sh
3bd0: 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 all set the valu
3be0: 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 e of.**
3bf0: 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 *E to NULL if E
3c00: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 is not NULL and
3c10: 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 there are no er
3c20: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 rors..**.** {H12
3c30: 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 137} The [sqlite
3c40: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 3_exec(D,S,C,A,E
3c50: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c )] function shal
3c60: 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72 6f 72 l set the [error
3c70: 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 code].**
3c80: 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61 and message a
3c90: 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 ccessible via [s
3ca0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
3cb0: 5d 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ], .**
3cc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
3cd0: 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a d_errcode()],.**
3ce0: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
3cf0: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e e3_errmsg()], an
3d00: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d [sqlite3_errms
3d10: 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 g16()]..**.** {H
3d20: 31 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 12138} If the S
3d30: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
3d40: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 lite3_exec(D,S,C
3d50: 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f ,A,E)] is NULL o
3d60: 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 r an.**
3d70: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 empty string or
3d80: 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e contains nothin
3d90: 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 g other than whi
3da0: 74 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 tespace, comment
3db0: 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 s,.** a
3dc0: 6e 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 nd/or semicolons
3dd0: 2c 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f , then results o
3de0: 66 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f f [sqlite3_errco
3df0: 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 de()],.**
3e00: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 [sqlite3_exte
3e10: 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c nded_errcode()],
3e20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
3e30: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c lite3_errmsg()],
3e40: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
3e50: 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 rmsg16()].**
3e60: 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 shall rese
3e70: 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f t to indicate no
3e80: 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 errors..**.** A
3e90: 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a SSUMPTIONS:.**.*
3ea0: 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20 66 * {A12141} The f
3eb0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
3ec0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 o [sqlite3_exec(
3ed0: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 )] must be an va
3ee0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 lid and open.**
3ef0: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
3f00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
3f10: 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 **.** {A12142} T
3f20: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
3f30: 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 ection must not
3f40: 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a be closed while.
3f50: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
3f60: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 ite3_exec()] is
3f70: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b running..**.** {
3f80: 41 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c A12143} The call
3f90: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f ing function sho
3fa0: 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 uld use [sqlite3
3fb0: 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 _free()] to free
3fc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
3fd0: 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 memory that *er
3fe0: 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 rmsg is left poi
3ff0: 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 nting at once th
4000: 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 e error.**
4010: 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e message is n
4020: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e o longer needed.
4030: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 .**.** {A12145}
4040: 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e The SQL statemen
4050: 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e t text in the 2n
4060: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
4070: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a sqlite3_exec()].
4080: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 ** must
4090: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 remain unchange
40a0: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 d while [sqlite3
40b0: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e _exec()] is runn
40c0: 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ing..*/.int sqli
40d0: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 te3_exec(. sqli
40e0: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 te3*,
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4100: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
4110: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
4120: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c const 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 20 20 2f 2a 20 53 51 /* SQ
4150: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 L to be evaluate
4160: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c d */. int (*cal
4170: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 lback)(void*,int
4180: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c ,char**,char**),
4190: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 /* Callback fu
41a0: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
41b0: 20 2a 2c 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 20 20 2f 2a 20 31 73 74 20 61 72 /* 1st ar
41e0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 gument to callba
41f0: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 ck */. char **e
4200: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 rrmsg
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4220: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
4230: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
4240: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
4250: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 EF: Result Codes
4260: 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 {H10210} <S1070
4270: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
4280: 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 SQLITE_OK {error
4290: 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f code} {error co
42a0: 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 des}.** KEYWORDS
42b0: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 : {result code}
42c0: 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a {result codes}.*
42d0: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 *.** Many SQLite
42e0: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
42f0: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 n an integer res
4300: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 ult code from th
4310: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 e set shown.** h
4320: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ere in order to
4330: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73 indicates succes
4340: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a s or failure..**
4350: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f .** New error co
4360: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 des may be added
4370: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
4380: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
4390: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
43a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
43b0: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 D | extended res
43c0: 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 ult codes].*/.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 efine SQLITE_OK
43e0: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 0 /*
43f0: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 Successful resu
4400: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 lt */./* beginni
4410: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 ng-of-error-code
4420: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c s */.#define SQL
4430: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 ITE_ERROR
4440: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 1 /* SQL erro
4450: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 r or missing dat
4460: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 abase */.#define
4470: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c SQLITE_INTERNAL
4480: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 2 /* Inte
4490: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 rnal logic error
44a0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 in SQLite */.#d
44b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 efine SQLITE_PER
44c0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a M 3 /*
44d0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 Access permissi
44e0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
44f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 fine SQLITE_ABOR
4500: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 T 4 /*
4510: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 Callback routine
4520: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 requested an ab
4530: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ort */.#define S
4540: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 QLITE_BUSY
4550: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 5 /* The da
4560: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c tabase file is l
4570: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ocked */.#define
4580: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 SQLITE_LOCKED
4590: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 6 /* A ta
45a0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 ble in the datab
45b0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f ase is locked */
45c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
45d0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 NOMEM 7
45e0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 /* A malloc() f
45f0: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ailed */.#define
4600: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
4610: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 8 /* Atte
4620: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 mpt to write a r
4630: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 eadonly database
4640: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4650: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 TE_INTERRUPT
4660: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 9 /* Operation
4670: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 terminated by s
4680: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
4690: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ()*/.#define SQL
46a0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 ITE_IOERR
46b0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 10 /* Some kin
46c0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 d of disk I/O er
46d0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a ror occurred */.
46e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
46f0: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 ORRUPT 11
4700: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
4710: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 disk image is ma
4720: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 lformed */.#defi
4730: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 ne SQLITE_NOTFOU
4740: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f ND 12 /* NO
4750: 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 T USED. Table or
4760: 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e record not foun
4770: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4780: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 ITE_FULL
4790: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 13 /* Insertio
47a0: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 n failed because
47b0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c database is ful
47c0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
47d0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 ITE_CANTOPEN
47e0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 14 /* Unable t
47f0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
4800: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
4810: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f ine SQLITE_PROTO
4820: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e COL 15 /* N
4830: 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 OT USED. Databas
4840: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 e lock protocol
4850: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
4860: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 SQLITE_EMPTY
4870: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 16 /* Data
4880: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f base is empty */
4890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48a0: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 SCHEMA 17
48b0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
48c0: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 schema changed
48d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
48e0: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 E_TOOBIG 18
48f0: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 /* String or
4900: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a BLOB exceeds siz
4910: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 e limit */.#defi
4920: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
4930: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 AINT 19 /* Ab
4940: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 ort due to const
4950: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 raint violation
4960: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4970: 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 E_MISMATCH 20
4980: 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 /* Data type
4990: 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 mismatch */.#def
49a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ine SQLITE_MISUS
49b0: 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c E 21 /* L
49c0: 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f ibrary used inco
49d0: 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 rrectly */.#defi
49e0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 ne SQLITE_NOLFS
49f0: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 22 /* Us
4a00: 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e es OS features n
4a10: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 ot supported on
4a20: 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 host */.#define
4a30: 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 SQLITE_AUTH
4a40: 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 23 /* Autho
4a50: 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 rization denied
4a60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4a70: 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 E_FORMAT 24
4a80: 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 /* Auxiliary
4a90: 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 database format
4aa0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
4ab0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 SQLITE_RANGE
4ac0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 25 /* 2nd
4ad0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
4ae0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 ite3_bind out of
4af0: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e range */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 e SQLITE_NOTADB
4b10: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 26 /* Fil
4b20: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 e opened that is
4b30: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
4b40: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
4b50: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 SQLITE_ROW
4b60: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 100 /* sqlit
4b70: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e e3_step() has an
4b80: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 other row ready
4b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4ba0: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 E_DONE 10
4bb0: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 1 /* sqlite3_st
4bc0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 ep() has finishe
4bd0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f d executing */./
4be0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 * end-of-error-c
4bf0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 odes */../*.** C
4c00: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 API3REF: Extende
4c10: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b d Result Codes {
4c20: 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e H10220} <S10700>
4c30: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
4c40: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
4c50: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 de} {extended er
4c60: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 ror codes}.** KE
4c70: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 YWORDS: {extende
4c80: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b d result code} {
4c90: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4ca0: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 codes}.**.** In
4cb0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4cc0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4cd0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4ce0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 eturn one of 26
4cf0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 integer.** [SQLI
4d00: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 TE_OK | result c
4d10: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c odes]. However,
4d20: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 experience has
4d30: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 shown that many
4d40: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 of.** these resu
4d50: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f lt codes are too
4d60: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e coarse-grained.
4d70: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 They do not pr
4d80: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 ovide as.** much
4d90: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
4da0: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 ut problems as p
4db0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 rogrammers might
4dc0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 like. In an ef
4dd0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 fort to.** addre
4de0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 ss this, newer v
4df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4e00: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 e (version 3.3.8
4e10: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c and later) incl
4e20: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 ude.** support f
4e30: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 or additional re
4e40: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 sult codes that
4e50: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 provide more det
4e60: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f ailed informatio
4e70: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 n.** about error
4e80: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 s. The extended
4e90: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4ea0: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
4eb0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 bled.** on a per
4ec0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
4ed0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 tion basis using
4ee0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4ef0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
4f00: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a _codes()] API..*
4f10: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 *.** Some of the
4f20: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e available exten
4f30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4f40: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 are listed here
4f50: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 ..** One may exp
4f60: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ect the number o
4f70: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c f extended resul
4f80: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 t codes will be
4f90: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 expand.** over t
4fa0: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 ime. Software t
4fb0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 hat uses extende
4fc0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 d result codes s
4fd0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 hould expect.**
4fe0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c to see new resul
4ff0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 t codes in futur
5000: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
5010: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
5020: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 SQLITE_OK result
5030: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 code will never
5040: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 be extended. I
5050: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a t will always.**
5060: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f be exactly zero
5070: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
5080: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 TS:.**.** {H1022
5090: 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 3} The symbolic
50a0: 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 name for an exte
50b0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
50c0: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a shall contains.
50d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 ** a re
50e0: 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 lated primary re
50f0: 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 sult code as a p
5100: 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 refix..**.** {H1
5110: 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 0224} Primary re
5120: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 sult code names
5130: 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 shall contain a
5140: 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61 single "_" chara
5150: 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 cter..**.** {H10
5160: 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65 225} Extended re
5170: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 sult code names
5180: 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 shall contain tw
5190: 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 o or more "_" ch
51a0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
51b0: 7b 48 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d {H10226} The num
51c0: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e eric value of an
51d0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
51e0: 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 code shall cont
51f0: 61 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ain the.**
5200: 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 numeric valu
5210: 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 e of its corresp
5220: 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 onding primary r
5230: 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a esult code in.**
5240: 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 its le
5250: 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 ast significant
5260: 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 8 bits..*/.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5280: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
52a0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
52b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
52c0: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 HORT_READ
52d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
52e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 SQLITE_IOERR_WR
5300: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ITE
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5320: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 SQLITE_IOERR_FSY
5340: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 NC (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5360: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f QLITE_IOERR_DIR_
5380: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 FSYNC (S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 QLITE_IOERR | (5
53a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 LITE_IOERR_TRUNC
53c0: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 ATE (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c LITE_IOERR | (6<
53e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
53f0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 ITE_IOERR_FSTAT
5400: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5410: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c ITE_IOERR | (7<<
5420: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5430: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 TE_IOERR_UNLOCK
5440: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5450: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 TE_IOERR | (8<<8
5460: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5470: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 E_IOERR_RDLOCK
5480: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5490: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 E_IOERR | (9<<8)
54a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
54b0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 _IOERR_DELETE
54c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
54d0: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 _IOERR | (10<<8)
54e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
54f0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 _IOERR_BLOCKED
5500: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5510: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 _IOERR | (11<<8)
5520: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5530: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 _IOERR_NOMEM
5540: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5550: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 _IOERR | (12<<8)
5560: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5570: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 _IOERR_ACCESS
5580: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5590: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 _IOERR | (13<<8)
55a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
55b0: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 _IOERR_CHECKRESE
55c0: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 RVEDLOCK (SQLITE
55d0: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 _IOERR | (14<<8)
55e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
55f0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 _IOERR_LOCK
5600: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5610: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 _IOERR | (15<<8)
5620: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
5630: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c F: Flags For Fil
5640: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e e Open Operation
5650: 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 s {H10230} <H111
5660: 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 20> <H12700>.**.
5670: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c ** These bit val
5680: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 ues are intended
5690: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a for use in the.
56a0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ** 3rd parameter
56b0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
56c0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
56d0: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 rface and.** in
56e0: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
56f0: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d r to the xOpen m
5700: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 ethod of the.**
5710: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
5720: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 ject..*/.#define
5730: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
5740: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 DONLY 0x
5750: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 00000001.#define
5760: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
5770: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 DWRITE 0x
5780: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 00000002.#define
5790: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
57a0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 ATE 0x
57b0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
57c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c SQLITE_OPEN_DEL
57d0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 ETEONCLOSE 0x
57e0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
57f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
5800: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 LUSIVE 0x
5810: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
5820: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 SQLITE_OPEN_MAI
5830: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 N_DB 0x
5840: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
5850: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d SQLITE_OPEN_TEM
5860: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 P_DB 0x
5870: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
5880: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 SQLITE_OPEN_TRA
5890: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 NSIENT_DB 0x
58a0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 00000400.#define
58b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 SQLITE_OPEN_MAI
58c0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 N_JOURNAL 0x
58d0: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 00000800.#define
58e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d SQLITE_OPEN_TEM
58f0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 P_JOURNAL 0x
5900: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 00001000.#define
5910: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 SQLITE_OPEN_SUB
5920: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 JOURNAL 0x
5930: 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 00002000.#define
5940: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 SQLITE_OPEN_MAS
5950: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 TER_JOURNAL 0x
5960: 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 00004000.#define
5970: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d SQLITE_OPEN_NOM
5980: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 UTEX 0x
5990: 30 30 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 00008000.#define
59a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c SQLITE_OPEN_FUL
59b0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 LMUTEX 0x
59c0: 30 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 00010000../*.**
59d0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
59e0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
59f0: 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 {H10240} <H1112
5a00: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 0>.**.** The xDe
5a10: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 viceCapabilities
5a20: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b method of the [
5a30: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
5a40: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ds].** object re
5a50: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
5a60: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 which is a vect
5a70: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a or of the these.
5a80: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 ** bit values ex
5a90: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 pressing I/O cha
5aa0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 racteristics of
5ab0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 the mass storage
5ac0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 .** device that
5ad0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 holds the file t
5ae0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
5af0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
5b00: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a refers to..**.**
5b10: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5b20: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 P_ATOMIC propert
5b30: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c y means that all
5b40: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e writes of.** an
5b50: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 y size are atomi
5b60: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
5b70: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 OCAP_ATOMICnnn v
5b80: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 alues.** mean th
5b90: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f at writes of blo
5ba0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e cks that are nnn
5bb0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
5bc0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 nd.** are aligne
5bd0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 d to an address
5be0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 which is an inte
5bf0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a ger multiple of.
5c00: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 ** nnn are atomi
5c10: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
5c20: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
5c30: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 value means.**
5c40: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 that when data i
5c50: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 s appended to a
5c60: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 file, the data i
5c70: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 s appended.** fi
5c80: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a rst then the siz
5c90: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 e of the file is
5ca0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 extended, never
5cb0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 the other.** wa
5cc0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 y around. The S
5cd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
5ce0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 ENTIAL property
5cf0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e means that.** in
5d00: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 formation is wri
5d10: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 tten to disk in
5d20: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 the same order a
5d30: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 s calls.** to xW
5d40: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 rite()..*/.#defi
5d50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5d60: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 ATOMIC
5d70: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
5d80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5d90: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 ATOMIC512
5da0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
5db0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5dc0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 ATOMIC1K
5dd0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
5de0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5df0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 ATOMIC2K
5e00: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 0x00000008.#defi
5e10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5e20: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 ATOMIC4K
5e30: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5e50: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
5e60: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 0x00000020.#defi
5e70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5e80: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 ATOMIC16K
5e90: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 0x00000040.#defi
5ea0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5eb0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 ATOMIC32K
5ec0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
5ed0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5ee0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
5ef0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
5f00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5f10: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
5f20: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 0x00000200.#defi
5f30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5f40: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 SEQUENTIAL
5f50: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 0x00000400../*.*
5f60: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 * CAPI3REF: File
5f70: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 Locking Levels
5f80: 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 {H10250} <H11120
5f90: 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a > <H11310>.**.**
5fa0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 SQLite uses one
5fb0: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
5fc0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
5fd0: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 second.** argume
5fe0: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d nt to calls it m
5ff0: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 akes to the xLoc
6000: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
6010: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 ) methods.** of
6020: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d an [sqlite3_io_m
6030: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a ethods] object..
6040: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6050: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 E_LOCK_NONE
6060: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
6070: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
6080: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 D 1.#defi
6090: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 ne SQLITE_LOCK_R
60a0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 ESERVED 2.#
60b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
60c0: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 CK_PENDING
60d0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
60e0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
60f0: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 4../*.** CA
6100: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e PI3REF: Synchron
6110: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 ization Type Fla
6120: 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 gs {H10260} <H11
6130: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 120>.**.** When
6140: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
6150: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f he xSync() metho
6160: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 d of an.** [sqli
6170: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
6180: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 object it uses a
6190: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
61a0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 ** these integer
61b0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
61c0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a econd argument..
61d0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 **.** When the S
61e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
61f0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 NLY flag is used
6200: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
6210: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 the.** sync oper
6220: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 ation only needs
6230: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 to flush data t
6240: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 o mass storage.
6250: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d Inode.** inform
6260: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 ation need not b
6270: 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 e flushed. The S
6280: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
6290: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 L flag means.**
62a0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 to use normal fs
62b0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e ync() semantics.
62c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 The SQLITE_SYNC
62d0: 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 _FULL flag means
62e0: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f .** to use Mac O
62f0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
6300: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 nc instead of fs
6310: 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e ync()..*/.#defin
6320: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
6330: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 RMAL 0x00
6340: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
6350: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 TE_SYNC_FULL
6360: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 0x00003.#d
6370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
6380: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 C_DATAONLY
6390: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 0x00010../*.** C
63a0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
63b0: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 rface Open File
63c0: 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 Handle {H11110}
63d0: 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 <S20110>.**.** A
63e0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
63f0: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
6400: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 ts an open file
6410: 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 in the OS.** int
6420: 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 erface layer. I
6430: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 ndividual OS int
6440: 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 erface implement
6450: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 ations will.** w
6460: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 ant to subclass
6470: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 this object by a
6480: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f ppending additio
6490: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f nal fields.** fo
64a0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e r their own use.
64b0: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 The pMethods e
64c0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 ntry is a pointe
64d0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 r to an.** [sqli
64e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
64f0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
6500: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 nes methods for
6510: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f performing.** I/
6520: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 O operations on
6530: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a the open file..*
6540: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
6550: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 sqlite3_file sq
6560: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 lite3_file;.stru
6570: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
6580: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 {. const struct
6590: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
65a0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 ods *pMethods;
65b0: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 /* Methods for a
65c0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d n open file */.}
65d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
65e0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
65f0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 File Virtual Met
6600: 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 hods Object {H11
6610: 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 120} <S20110>.**
6620: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f .** Every file o
6630: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 pened by the [sq
6640: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e lite3_vfs] xOpen
6650: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 method populate
6660: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s an.** [sqlite3
6670: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f _file] object (o
6680: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 r, more commonly
6690: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 , a subclass of
66a0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
66b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 file] object) wi
66c0: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 th a pointer to
66d0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
66e0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 his object..** T
66f0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
6700: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 es the methods u
6710: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 sed to perform v
6720: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e arious operation
6730: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 s.** against the
6740: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 open file repre
6750: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 sented by the [s
6760: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
6770: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ect..**.** The f
6780: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
6790: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e xSync may be on
67a0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e e of [SQLITE_SYN
67b0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 C_NORMAL] or.**
67c0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c [SQLITE_SYNC_FUL
67d0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 L]. The first c
67e0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 hoice is the nor
67f0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 mal fsync()..**
6800: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 The second choic
6810: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 e is a Mac OS X
6820: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 style fullsync.
6830: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e The [SQLITE_SYN
6840: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 C_DATAONLY].** f
6850: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 lag may be ORed
6860: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 in to indicate t
6870: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 hat only the dat
6880: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a a of the file.**
6890: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f and not its ino
68a0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 de needs to be s
68b0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ynced..**.** The
68c0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
68d0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 to xLock() and x
68e0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 Unlock() are one
68f0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c of.** <ul>.** <
6900: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
6910: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _NONE],.** <li>
6920: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
6930: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 RED],.** <li> [S
6940: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
6950: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 VED],.** <li> [S
6960: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
6970: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 NG], or.** <li>
6980: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
6990: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c LUSIVE]..** </ul
69a0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 >.** xLock() inc
69b0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
69c0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 xUnlock() decre
69d0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a ases the lock..*
69e0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 * The xCheckRese
69f0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f rvedLock() metho
6a00: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 d checks whether
6a10: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
6a20: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 nnection,.** eit
6a30: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 her in this proc
6a40: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f ess or in some o
6a50: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 ther process, is
6a60: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 holding a RESER
6a70: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c VED,.** PENDING,
6a80: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f or EXCLUSIVE lo
6a90: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 ck on the file.
6aa0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 It returns true
6ab0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f .** if such a lo
6ac0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 ck exists and fa
6ad0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a lse otherwise..*
6ae0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f *.** The xFileCo
6af0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 ntrol() method i
6b00: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 s a generic inte
6b10: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 rface that allow
6b20: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 s custom.** VFS
6b30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
6b40: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 to directly cont
6b50: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 rol an open file
6b60: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
6b70: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
6b80: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
6b90: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f . The second "o
6ba0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 p" argument is a
6bb0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 n.** integer opc
6bc0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 ode. The third
6bd0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 argument is a ge
6be0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e neric pointer in
6bf0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 tended to.** poi
6c00: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 nt to a structur
6c10: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 e that may conta
6c20: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 in arguments or
6c30: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 space in which t
6c40: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 o.** write retur
6c50: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e n values. Poten
6c60: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 tial uses for xF
6c70: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 ileControl() mig
6c80: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f ht be.** functio
6c90: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f ns to enable blo
6ca0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 cking locks with
6cb0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 timeouts, to ch
6cc0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b ange the.** lock
6cd0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f ing strategy (fo
6ce0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 r example to use
6cf0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 dot-file locks)
6d00: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 , to inquire.**
6d10: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 about the status
6d20: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 of a lock, or t
6d30: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f o break stale lo
6d40: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 cks. The SQLite
6d50: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 .** core reserve
6d60: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 s all opcodes le
6d70: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 ss than 100 for
6d80: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 its own use..**
6d90: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f A [SQLITE_FCNTL_
6da0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 LOCKSTATE | list
6db0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 of opcodes] les
6dc0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 s than 100 is av
6dd0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c ailable..** Appl
6de0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 ications that de
6df0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 fine a custom xF
6e00: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
6e10: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 d should use opc
6e20: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 odes.** greater
6e30: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 than 100 to avoi
6e40: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a d conflicts..**.
6e50: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 ** The xSectorSi
6e60: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 ze() method retu
6e70: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 rns the sector s
6e80: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 ize of the.** de
6e90: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c vice that underl
6ea0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 ies the file. T
6eb0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 he sector size i
6ec0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d s the.** minimum
6ed0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 write that can
6ee0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 be performed wit
6ef0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a hout disturbing.
6f00: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 ** other bytes i
6f10: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 n the file. The
6f20: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
6f30: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 ristics().** met
6f40: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 hod returns a bi
6f50: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 t vector describ
6f60: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 ing behaviors of
6f70: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
6f80: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a ng device:.**.**
6f90: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
6fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6fb0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c IC].** <li> [SQL
6fc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6fd0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 512].** <li> [SQ
6fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6ff0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C1K].** <li> [SQ
7000: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7010: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C2K].** <li> [SQ
7020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7030: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C4K].** <li> [SQ
7040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7050: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C8K].** <li> [SQ
7060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7070: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C16K].** <li> [S
7080: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7090: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC32K].** <li> [
70a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
70b0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC64K].** <li>
70c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 [SQLITE_IOCAP_SA
70d0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c FE_APPEND].** <l
70e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
70f0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 _SEQUENTIAL].**
7100: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
7110: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7120: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
7130: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
7140: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
7150: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
7160: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
7170: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
7180: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
7190: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
71a0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
71b0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
71c0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
71d0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
71e0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
71f0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
7200: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
7210: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
7220: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
7230: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
7240: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
7250: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
7260: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
7270: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
7280: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
7290: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
72a0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
72b0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
72c0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
72d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
72e0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
72f0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
7300: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
7310: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
7320: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
7330: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
7340: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 )..**.** If xRea
7350: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 d() returns SQLI
7360: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
7370: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f EAD it must also
7380: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 fill.** in the
7390: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 unread portions
73a0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 of the buffer wi
73b0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 th zeros. A VFS
73c0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 that.** fails t
73d0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
73e0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 t reads might se
73f0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 em to work. How
7400: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 ever,.** failure
7410: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
7420: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 ort reads will e
7430: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 ventually lead t
7440: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f o.** database co
7450: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 rruption..*/.typ
7460: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
7470: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 te3_io_methods s
7480: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7490: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
74a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 3_io_methods {.
74b0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
74c0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 int (*xClose)(s
74d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
74e0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 int (*xRead)(sq
74f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 lite3_file*, voi
7500: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
7510: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
7520: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 t);. int (*xWri
7530: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
7540: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
7550: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
7560: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
7570: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 int (*xTruncat
7580: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
7590: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
75a0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
75b0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 Sync)(sqlite3_fi
75c0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b le*, int flags);
75d0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 . int (*xFileSi
75e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
75f0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
7600: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 *pSize);. int
7610: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 (*xLock)(sqlite3
7620: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 _file*, int);.
7630: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 int (*xUnlock)(s
7640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
7650: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 t);. int (*xChe
7660: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 ckReservedLock)(
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
7680: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
7690: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 int (*xFileContr
76a0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ol)(sqlite3_file
76b0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 *, int op, void
76c0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a *pArg);. int (*
76d0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c xSectorSize)(sql
76e0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
76f0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 nt (*xDeviceChar
7700: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c acteristics)(sql
7710: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f ite3_file*);. /
7720: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
7730: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
7740: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
7750: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
7760: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
7770: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
7780: 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 l Opcodes {H1131
7790: 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 0} <S30800>.**.*
77a0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
77b0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 constants are op
77c0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 codes for the xF
77d0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
77e0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c d.** of the [sql
77f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
7800: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 object and for
7810: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
7820: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 e_control()].**
7830: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
7840: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
7850: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 TL_LOCKSTATE] op
7860: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 code is used for
7870: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 debugging. Thi
7880: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 s.** opcode caus
7890: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 es the xFileCont
78a0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 rol method to wr
78b0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 ite the current
78c0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 state of.** the
78d0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 lock (one of [SQ
78e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c LITE_LOCK_NONE],
78f0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
7900: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ARED],.** [SQLIT
7910: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d E_LOCK_RESERVED]
7920: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 , [SQLITE_LOCK_P
7930: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c ENDING], or [SQL
7940: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
7950: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 VE]).** into an
7960: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 integer that the
7970: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 pArg argument p
7980: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 oints to. This c
7990: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
79a0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
79b0: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 ing and only nee
79c0: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ds to be support
79d0: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 ed when SQLITE_T
79e0: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 EST.** is define
79f0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d..*/.#define SQ
7a00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
7a10: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f TATE 1../
7a20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
7a30: 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 utex Handle {H17
7a40: 31 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 110} <S20130>.**
7a50: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
7a60: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
7a70: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
7a80: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
7a90: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
7aa0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
7ab0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
7ac0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
7ad0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
7ae0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
7af0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
7b00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
7b10: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
7b20: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
7b30: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
7b40: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
7b50: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
7b60: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
7b70: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
7b80: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
7b90: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
7ba0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
7bb0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
7bc0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
7bd0: 61 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 ace Object {H111
7be0: 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 40} <S20100>.**.
7bf0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
7c00: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
7c10: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
7c20: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 the interface b
7c30: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 etween.** the SQ
7c40: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 Lite core and th
7c50: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
7c60: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
7c70: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 The "vfs".** in
7c80: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
7c90: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f object stands fo
7ca0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 r "virtual file
7cb0: 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 system"..**.** T
7cc0: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
7cd0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 iVersion field i
7ce0: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 s initially 1 bu
7cf0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 t may be larger
7d00: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 in.** future ver
7d10: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
7d20: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 Additional fie
7d30: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e lds may be appen
7d40: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f ded to this.** o
7d50: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 bject when the i
7d60: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 Version value is
7d70: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 increased. Not
7d80: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 e that the struc
7d90: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 ture.** of the s
7da0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
7db0: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 t changes in the
7dc0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 transaction bet
7dd0: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 ween.** SQLite v
7de0: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 ersion 3.5.9 and
7df0: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 3.6.0 and yet t
7e00: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c he iVersion fiel
7e10: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 d was not.** mod
7e20: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ified..**.** The
7e30: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 szOsFile field
7e40: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
7e50: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 he subclassed [s
7e60: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 qlite3_file].**
7e70: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 structure used b
7e80: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 y this VFS. mxP
7e90: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d athname is the m
7ea0: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
7eb0: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 .** a pathname i
7ec0: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a n this VFS..**.*
7ed0: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c * Registered sql
7ee0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 ite3_vfs objects
7ef0: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c are kept on a l
7f00: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 inked list forme
7f10: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 d by.** the pNex
7f20: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 t pointer. The
7f30: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 [sqlite3_vfs_reg
7f40: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 ister()].** and
7f50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 [sqlite3_vfs_unr
7f60: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 egister()] inter
7f70: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 faces manage thi
7f80: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 s list.** in a t
7f90: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 hread-safe way.
7fa0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
7fb0: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 s_find()] interf
7fc0: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 ace.** searches
7fd0: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 the list. Neith
7fe0: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
7ff0: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 on code nor the
8000: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 VFS.** implement
8010: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ation should use
8020: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
8030: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e er..**.** The pN
8040: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 ext field is the
8050: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 only field in t
8060: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
8070: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 * structure that
8080: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 SQLite will eve
8090: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 r modify. SQLit
80a0: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 e will only acce
80b0: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 ss.** or modify
80c0: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 this field while
80d0: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 holding a parti
80e0: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 cular static mut
80f0: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ex..** The appli
8100: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 cation should ne
8110: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 ver modify anyth
8120: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 ing within the s
8130: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 qlite3_vfs.** ob
8140: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 ject once the ob
8150: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 ject has been re
8160: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 gistered..**.**
8170: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 The zName field
8180: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f holds the name o
8190: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 f the VFS module
81a0: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 . The name must
81b0: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 .** be unique ac
81c0: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 ross all VFS mod
81d0: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 ules..**.** {H11
81e0: 31 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 141} SQLite will
81f0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
8200: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
8210: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
8220: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 .** is either a
8230: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 NULL pointer or
8240: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a string obtained.
8250: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 ** from xFullPat
8260: 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 hname(). SQLite
8270: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
8280: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
8290: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
82a0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
82b0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
82c0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
82d0: 7b 45 4e 44 7d 20 20 42 65 63 61 75 73 65 20 6f {END} Because o
82e0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 f the previous s
82f0: 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 entense,.** the
8300: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 [sqlite3_file] c
8310: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 an safely store
8320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
8330: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 .** filename if
8340: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 it needs to reme
8350: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d mber the filenam
8360: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f e for some reaso
8370: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 n..** If the zFi
8380: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
8390: 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e is xOpen is a N
83a0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
83b0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 xOpen.** must i
83c0: 6e 76 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65 nvite its own te
83d0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 mporary name for
83e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e the file. When
83f0: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 ever the .** xFi
8400: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
8410: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c is NULL it will
8420: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 also be the cas
8430: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c e that the.** fl
8440: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 ags parameter wi
8450: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ll include [SQLI
8460: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
8470: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 CLOSE]..**.** {H
8480: 31 31 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 11142} The flags
8490: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
84a0: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c en() includes al
84b0: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a l bits set in.**
84c0: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
84d0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
84e0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 open_v2()]. Or
84f0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e if [sqlite3_open
8500: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
8510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 e3_open16()] is
8520: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 used, then flags
8530: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 includes at lea
8540: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 st.** [SQLITE_OP
8550: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
8560: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
8570: 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 ATE]. {END}.** I
8580: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 f xOpen() opens
8590: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 a file read-only
85a0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 then it sets *p
85b0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 OutFlags to.** i
85c0: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f nclude [SQLITE_O
85d0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 PEN_READONLY].
85e0: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 Other bits in *p
85f0: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 OutFlags may be
8600: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 set..**.** {H111
8610: 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 43} SQLite will
8620: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
8630: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
8640: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
8650: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 ().** call, depe
8660: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a nding on the obj
8670: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 ect being opened
8680: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
8690: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
86a0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c EN_MAIN_DB].** <
86b0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
86c0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a N_MAIN_JOURNAL].
86d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
86e0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a _OPEN_TEMP_DB].*
86f0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
8700: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
8710: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
8720: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
8730: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 NT_DB].** <li>
8740: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 [SQLITE_OPEN_SUB
8750: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
8760: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
8770: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a ASTER_JOURNAL].*
8780: 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a * </ul> {END}.**
8790: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f .** The file I/O
87a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
87b0: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 can use the obje
87c0: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f ct type flags to
87d0: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 .** change the w
87e0: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 ay it deals with
87f0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 files. For exa
8800: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 mple, an applica
8810: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 tion.** that doe
8820: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 s not care about
8830: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 crash recovery
8840: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 or rollback migh
8850: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 t make.** the op
8860: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 en of a journal
8870: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 file a no-op. W
8880: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f rites to this jo
8890: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 urnal would.** a
88a0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 lso be no-ops, a
88b0: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 nd any attempt t
88c0: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e o read the journ
88d0: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a al would return.
88e0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e ** SQLITE_IOERR.
88f0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 Or the impleme
8900: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ntation might re
8910: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 cognize that a d
8920: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
8930: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 will be doing pa
8940: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f ge-aligned secto
8950: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 r reads and writ
8960: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a es in a random.*
8970: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 * order and set
8980: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 up its I/O subsy
8990: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 stem accordingly
89a0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d ..**.** SQLite m
89b0: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e ight also add on
89c0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
89d0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
89e0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a xOpen method:.**
89f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
8a00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
8a10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
8a20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
8a30: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 N_EXCLUSIVE].**
8a40: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 </ul>.**.** {H11
8a50: 31 34 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 145} The [SQLITE
8a60: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
8a70: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 OSE] flag means
8a80: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
8a90: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 be.** deleted wh
8aa0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e en it is closed.
8ab0: 20 20 7b 48 31 31 31 34 36 7d 20 54 68 65 20 5b {H11146} The [
8ac0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
8ad0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 TEONCLOSE].** wi
8ae0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 ll be set for TE
8af0: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a MP databases, j
8b00: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 ournals and for
8b10: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a subjournals..**.
8b20: 2a 2a 20 7b 48 31 31 31 34 37 7d 20 54 68 65 20 ** {H11147} The
8b30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
8b40: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 LUSIVE] flag mea
8b50: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
8b60: 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 ld be opened.**
8b70: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 for exclusive ac
8b80: 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 cess. This flag
8b90: 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 is set for all
8ba0: 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 files except.**
8bb0: 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 for the main dat
8bc0: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a abase file..**.*
8bd0: 2a 20 7b 48 31 31 31 34 38 7d 20 41 74 20 6c 65 * {H11148} At le
8be0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 ast szOsFile byt
8bf0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 es of memory are
8c00: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
8c10: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 Lite.** to hold
8c20: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
8c30: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 le] structure pa
8c40: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
8c50: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
8c60: 20 78 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 xOpen. {END} T
8c70: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
8c80: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f does not have to
8c90: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 .** allocate the
8ca0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 structure; it s
8cb0: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 hould just fill
8cc0: 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 it in..**.** {H1
8cd0: 31 31 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 1149} The flags
8ce0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 argument to xAcc
8cf0: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 ess() may be [SQ
8d00: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
8d10: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 TS].** to test f
8d20: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 or the existence
8d30: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b of a file, or [
8d40: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
8d50: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 ADWRITE] to.** t
8d60: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 est whether a fi
8d70: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 le is readable a
8d80: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 nd writable, or
8d90: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
8da0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 EAD].** to test
8db0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
8dc0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 s at least reada
8dd0: 62 6c 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 ble. {END} The
8de0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a file can be a.**
8df0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a directory..**.*
8e00: 2a 20 7b 48 31 31 31 35 30 7d 20 53 51 4c 69 74 * {H11150} SQLit
8e10: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c e will always al
8e20: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 locate at least
8e30: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 mxPathname+1 byt
8e40: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 es for the.** ou
8e50: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c tput buffer xFul
8e60: 6c 50 61 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31 lPathname. {H111
8e70: 35 31 7d 20 54 68 65 20 65 78 61 63 74 20 73 69 51} The exact si
8e80: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 ze of the output
8e90: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c buffer.** is al
8ea0: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 so passed as a p
8eb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 arameter to both
8ec0: 20 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d methods. {END}
8ed0: 20 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 If the output
8ee0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 buffer.** is not
8ef0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b large enough, [
8f00: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
8f10: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
8f20: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 ned. Since this
8f30: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 is.** handled as
8f40: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 a fatal error b
8f50: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d y SQLite, vfs im
8f60: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
8f70: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a ould endeavor.**
8f80: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 to prevent this
8f90: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 by setting mxPa
8fa0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 thname to a suff
8fb0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 iciently large v
8fc0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
8fd0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 xRandomness(), x
8fe0: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 Sleep(), and xCu
8ff0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 rrentTime() inte
9000: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f rfaces.** are no
9010: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 t strictly a par
9020: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 t of the filesys
9030: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 tem, but they ar
9040: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e e.** included in
9050: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 the VFS structu
9060: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e re for completen
9070: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e ess..** The xRan
9080: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 domness() functi
9090: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 on attempts to r
90a0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 eturn nBytes byt
90b0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 es.** of good-qu
90c0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 ality randomness
90d0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 into zOut. The
90e0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 return value is
90f0: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e .** the actual n
9100: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
9110: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 f randomness obt
9120: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 ained..** The xS
9130: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 leep() method ca
9140: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 uses the calling
9150: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 thread to sleep
9160: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 for at.** least
9170: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d the number of m
9180: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 icroseconds give
9190: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 n. The xCurrent
91a0: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 Time().** method
91b0: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 returns a Julia
91c0: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 n Day Number for
91d0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 the current dat
91e0: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 e and time..*/.t
91f0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
9200: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 lite3_vfs sqlite
9210: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 3_vfs;.struct sq
9220: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e lite3_vfs {. in
9230: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 t iVersion;
9240: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 /* Struct
9250: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 ure version numb
9260: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 er */. int szOs
9270: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
9280: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
9290: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
92a0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
92b0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
92c0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
92d0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
92e0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
92f0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
9300: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
9310: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
9320: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
9330: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
9340: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
9350: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
9360: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
9370: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
9380: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
9390: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
93a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
93b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
93c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
93d0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
93e0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
93f0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
9400: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
9410: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
9420: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
9430: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
9440: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
9450: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
9460: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
9470: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
9480: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
9490: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
94a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
94b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
94c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
94d0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
94e0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
94f0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
9500: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
9510: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
9520: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
9530: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
9540: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
9550: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
9560: 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 id *(*xDlSym)(sq
9570: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a lite3_vfs*,void*
9580: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 , const char *zS
9590: 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 ymbol);. void (
95a0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
95b0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
95c0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
95d0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
95e0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
95f0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
9600: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
9610: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
9620: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
9630: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
9640: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
9650: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
9660: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
9670: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
9680: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
9690: 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 /* New fields ma
96a0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
96b0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 figure versions
96c0: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
96d0: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
96e0: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
96f0: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
9700: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
9710: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
9720: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 r the xAccess VF
9730: 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 S method {H11190
9740: 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a } <H11140>.**.**
9750: 20 7b 48 31 31 31 39 31 7d 20 54 68 65 73 65 20 {H11191} These
9760: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
9770: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 s can be used as
9780: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
9790: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 eter to.** the x
97a0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 Access method of
97b0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 an [sqlite3_vfs
97c0: 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 ] object. {END}
97d0: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a They determine.
97e0: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 ** what kind of
97f0: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 permissions the
9800: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 xAccess method i
9810: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a s looking for..*
9820: 2a 20 7b 48 31 31 31 39 32 7d 20 57 69 74 68 20 * {H11192} With
9830: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
9840: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 ISTS, the xAcces
9850: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 s method.** simp
9860: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ly checks whethe
9870: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 r the file exist
9880: 73 2e 0a 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57 s..** {H11193} W
9890: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
98a0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 S_READWRITE, the
98b0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
98c0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
98d0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f r the file is bo
98e0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 th readable and
98f0: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 writable..** {H1
9900: 31 31 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54 1194} With SQLIT
9910: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
9920: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
9930: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
9940: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
9950: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 readable..*/.#de
9960: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
9970: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 SS_EXISTS 0.#
9980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
9990: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 CESS_READWRITE 1
99a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
99b0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 ACCESS_READ
99c0: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 2../*.** CAPI3R
99d0: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 EF: Initialize T
99e0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
99f0: 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 y {H10130} <S200
9a00: 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 00><S30100>.**.*
9a10: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
9a20: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
9a30: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
9a40: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
9a50: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
9a60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f e3_shutdown() ro
9a70: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 utine.** dealloc
9a80: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 ates any resourc
9a90: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c es that were all
9aa0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 ocated by sqlite
9ab0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 3_initialize()..
9ac0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
9ad0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9ae0: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 ze() is an "effe
9af0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
9b00: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 t is.** the firs
9b10: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
9b20: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
9b30: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 nvoked during th
9b40: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a e lifetime of.**
9b50: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 the process, or
9b60: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
9b70: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
9b80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
9b90: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c invoked.** foll
9ba0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 owing a call to
9bb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
9bc0: 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 (). Only an eff
9bd0: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f ective call.** o
9be0: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 f sqlite3_initia
9bf0: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 lize() does any
9c00: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 initialization.
9c10: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 All other calls
9c20: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 .** are harmless
9c30: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 no-ops..**.** A
9c40: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
9c50: 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 s, sqlite3_initi
9c60: 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e alize() shall in
9c70: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
9c80: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
9c90: 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 larly, sqlite3_s
9ca0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 hutdown().** sha
9cb0: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
9cc0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
9cd0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
9ce0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
9cf0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
9d00: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
9d10: 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d s..** If for som
9d20: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 e reason, sqlite
9d30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
9d40: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 s unable to init
9d50: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 ialize.** the li
9d60: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 brary (perhaps i
9d70: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 t is unable to a
9d80: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 llocate a needed
9d90: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a resource such.*
9da0: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 * as a mutex) it
9db0: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 returns an [err
9dc0: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 or code] other t
9dd0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e han [SQLITE_OK].
9de0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
9df0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9e00: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
9e10: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
9e20: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 many other.** SQ
9e30: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
9e40: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 so that an appli
9e50: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 cation usually d
9e60: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a oes not need to.
9e70: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
9e80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
9e90: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 irectly. For ex
9ea0: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f ample, [sqlite3_
9eb0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 open()].** calls
9ec0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9ed0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c ize() so the SQL
9ee0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
9ef0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
9f00: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 y.** initialized
9f10: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f when [sqlite3_o
9f20: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 pen()] is called
9f30: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 if it has not b
9f40: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a e initialized.**
9f50: 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 already. Howev
9f60: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 er, if SQLite is
9f70: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
9f80: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
9f90: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d AUTOINIT].** com
9fa0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
9fb0: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d , then the autom
9fc0: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 atic calls to sq
9fd0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9fe0: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 ().** are omitte
9ff0: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 d and the applic
a000: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 ation must call
a010: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
a020: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a ze() directly.**
a030: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
a040: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
a050: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 interface. For
a060: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 maximum portabi
a070: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 lity,.** it is r
a080: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
a090: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 applications alw
a0a0: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ays invoke sqlit
a0b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
a0c0: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f ** directly prio
a0d0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f r to using any o
a0e0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
a0f0: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 rface. Future r
a100: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 eleases.** of SQ
a110: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 Lite may require
a120: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 this. In other
a130: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 words, the beha
a140: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a vior exhibited.*
a150: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
a160: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
a170: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
a180: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f INIT] might beco
a190: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c me the.** defaul
a1a0: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f t behavior in so
a1b0: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
a1c0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a e of SQLite..**.
a1d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
a1e0: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 s_init() routine
a1f0: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d does operating-
a200: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a system specific.
a210: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ** initializatio
a220: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 n of the SQLite
a230: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 library. The sq
a240: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
a250: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 * routine undoes
a260: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 the effect of s
a270: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a280: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 . Typical tasks
a290: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 .** performed by
a2a0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
a2b0: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 include allocati
a2c0: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 on or deallocati
a2d0: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 on.** of static
a2e0: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 resources, initi
a2f0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f alization of glo
a300: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a bal variables,.*
a310: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 * setting up a d
a320: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
a330: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 vfs] module, or
a340: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 setting up.** a
a350: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
a360: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c ation using [sql
a370: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a ite3_config()]..
a380: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
a390: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
a3a0: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 er invoke either
a3b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
a3c0: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
a3d0: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 _os_end() direct
a3e0: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 ly. The applica
a3f0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 tion should only
a400: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
a410: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
a420: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 and sqlite3_shut
a430: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c down(). The sql
a440: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
a450: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 * interface is c
a460: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 alled automatica
a470: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 lly by sqlite3_i
a480: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a nitialize() and.
a490: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ** sqlite3_os_en
a4a0: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 d() is called by
a4b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
a4c0: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 n(). Appropriat
a4d0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
a4e0: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 ions for sqlite3
a4f0: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
a500: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
a510: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 ** are built int
a520: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 o SQLite when it
a530: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 is compiled for
a540: 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 unix, windows,
a550: 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e or os/2..** When
a560: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
a570: 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e platforms (usin
a580: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 g the [SQLITE_OS
a590: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c _OTHER=1] compil
a5a0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
a5b0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f ) the applicatio
a5c0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 n must supply a
a5d0: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 suitable impleme
a5e0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 ntation for.** s
a5f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a600: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
a610: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 end(). An appli
a620: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a cation-supplied.
a630: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
a640: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f n of sqlite3_os_
a650: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 init() or sqlite
a660: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 3_os_end().** mu
a670: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 st return [SQLIT
a680: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
a690: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 and some other
a6a0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f [error code] upo
a6b0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f n.** failure..*/
a6c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 .int sqlite3_ini
a6d0: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 tialize(void);.i
a6e0: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nt sqlite3_shutd
a6f0: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 own(void);.int s
a700: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 qlite3_os_init(v
a710: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
a720: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 3_os_end(void);.
a730: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
a740: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 Configuring The
a750: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 SQLite Library
a760: 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 {H14100} <S20000
a770: 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 ><S30200>.** EXP
a780: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
a790: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
a7a0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
a7b0: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 s used to make g
a7c0: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 lobal configurat
a7d0: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
a7e0: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 o SQLite in orde
a7f0: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 r to tune SQLite
a800: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 to the specific
a810: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 needs of.** the
a820: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 application. T
a830: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 he default confi
a840: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f guration is reco
a850: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 mmended for most
a860: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
a870: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 and so this rou
a880: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 tine is usually
a890: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 not necessary.
a8a0: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 It is.** provide
a8b0: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 d to support rar
a8c0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 e applications w
a8d0: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 ith unusual need
a8e0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
a8f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
a900: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 terface is not t
a910: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 hreadsafe. The
a920: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d application.** m
a930: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 ust insure that
a940: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 no other SQLite
a950: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
a960: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a nvoked by other.
a970: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 ** threads while
a980: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
a990: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 ) is running. F
a9a0: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 urthermore, sqli
a9b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 te3_config().**
a9c0: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f may only be invo
a9d0: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 ked prior to lib
a9e0: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 rary initializat
a9f0: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
aa00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
aa10: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 ()] or after shu
aa20: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 tdown by [sqlite
aa30: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
aa40: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c * Note, however,
aa50: 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f that sqlite3_co
aa60: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
aa70: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
aa80: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
aa90: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
aaa0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
aab0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
aac0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
aad0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
aae0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
aaf0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
ab00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
ab10: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c G_SINGLETHREAD |
ab20: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
ab30: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
ab40: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
ab50: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
ab60: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
ab70: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
ab80: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
ab90: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
aba0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f n the [SQLITE_CO
abb0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
abc0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f D | configuratio
abd0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
abe0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
abf0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 nt..**.** When a
ac00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
ac10: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 ption is set, sq
ac20: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 lite3_config() r
ac30: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
ac40: 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 K]..** If the op
ac50: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 tion is unknown
ac60: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 or SQLite is una
ac70: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f ble to set the o
ac80: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 ption.** then th
ac90: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
aca0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 ns a non-zero [e
acb0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
acc0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
acd0: 0a 2a 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 .** {H14103} A s
ace0: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
acf0: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
ad00: 5f 63 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c _config()] shall
ad10: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
ad20: 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e [SQLITE_OK].
ad30: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 .**.** {H14106}
ad40: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e The [sqlite3_con
ad50: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
ad60: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 shall return [S
ad70: 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a QLITE_MISUSE].**
ad80: 20 20 20 20 20 20 20 20 20 20 69 66 20 69 74 20 if it
ad90: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 is invoked in be
ada0: 74 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b tween calls to [
adb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
adc0: 7a 65 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 ze()] and.**
add0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
ade0: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a hutdown()]..**.*
adf0: 2a 20 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 * {H14120} A suc
ae00: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
ae10: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
ae20: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
ae30: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a SINGLETHREAD]).*
ae40: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
ae50: 20 73 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 set the default
ae60: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
ae70: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 ] to Single-thre
ae80: 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 ad..**.** {H1412
ae90: 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 3} A successful
aea0: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
aeb0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 _config]([SQLITE
aec0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
aed0: 45 41 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 EAD]).**
aee0: 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 shall set the
aef0: 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 default [threadi
af00: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 ng mode] to Mult
af10: 69 2d 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 i-thread..**.**
af20: 7b 48 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 {H14126} A succe
af30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
af40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
af50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
af60: 52 49 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 RIALIZED]).**
af70: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 shall set
af80: 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 the default [th
af90: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
afa0: 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a Serialized..**.
afb0: 2a 2a 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 ** {H14129} A su
afc0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
afd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
afe0: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
aff0: 5f 4d 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 _MUTEX],X).**
b000: 20 20 20 20 20 20 20 77 68 65 72 65 20 58 20 69 where X i
b010: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
b020: 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 n initialized [s
b030: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
b040: 68 6f 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 hods].**
b050: 20 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 object shall c
b060: 61 75 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 ause all subsequ
b070: 65 6e 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 ent mutex operat
b080: 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a ions performed.*
b090: 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 53 51 * by SQ
b0a0: 4c 69 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 Lite to use the
b0b0: 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 mutex methods th
b0c0: 61 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 at were present
b0d0: 69 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 in X.**
b0e0: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c during the call
b0f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b100: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 fig()]..**.** {H
b110: 31 34 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 14132} A success
b120: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
b130: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
b140: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
b150: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 UTEX],X).**
b160: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20 where X is
b170: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
b180: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
b190: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a ethods] object .
b1a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
b1b0: 6c 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 l overwrite the
b1c0: 63 6f 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 content of [sqli
b1d0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
b1e0: 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 s] object.**
b1f0: 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d with the m
b200: 75 74 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 utex methods cur
b210: 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 rently in use by
b220: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b SQLite..**.** {
b230: 48 31 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 H14135} A succes
b240: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
b250: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b260: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
b270: 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 LOC],M).**
b280: 20 20 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 where M is a
b290: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
b2a0: 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 nitialized [sqli
b2b0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
b2c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a .** obj
b2d0: 65 63 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 ect shall cause
b2e0: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d all subsequent m
b2f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b300: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 operations.**
b310: 20 20 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 performe
b320: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 d by SQLite to u
b330: 73 65 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 se the methods t
b340: 68 61 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 hat were present
b350: 20 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 in .**
b360: 20 4d 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 M during the ca
b370: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
b380: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 onfig()]..**.**
b390: 7b 48 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 {H14138} A succe
b3a0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
b3b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
b3c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
b3d0: 54 4d 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 TMALLOC],M).**
b3e0: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 where M
b3f0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
b400: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f an [sqlite3_mem_
b410: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
b420: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 shall.**
b430: 20 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 overwrite the
b440: 63 6f 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 content of [sqli
b450: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
b460: 20 6f 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a object with .**
b470: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 the me
b480: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
b490: 6d 65 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c methods currentl
b4a0: 79 20 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 y in use by.**
b4b0: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a SQLite..
b4c0: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 **.** {H14141} A
b4d0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
b4e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b4f0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
b500: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 FIG_MEMSTATUS],1
b510: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ).** sh
b520: 61 6c 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d all enable the m
b530: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b540: 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 status collecti
b550: 6f 6e 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 on logic..**.**
b560: 7b 48 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 {H14144} A succe
b570: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
b580: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
b590: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
b5a0: 4d 53 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 MSTATUS],0).**
b5b0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 shall di
b5c0: 73 61 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 sable the memory
b5d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
b5e0: 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f us collection lo
b5f0: 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 gic..**.** {H141
b600: 34 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 47} The memory a
b610: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 llocation status
b620: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 collection logi
b630: 63 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 c shall be.**
b640: 20 20 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 enabled b
b650: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a y default..**.**
b660: 20 7b 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 {H14150} A succ
b670: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
b680: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
b690: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
b6a0: 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a CRATCH],S,Z,N).*
b6b0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 * where
b6c0: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e Z and N are non
b6d0: 2d 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 -negative intege
b6e0: 72 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 rs and .**
b6f0: 20 20 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 S is a point
b700: 65 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 er to an aligned
b710: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e memory buffer n
b720: 6f 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 ot less than.**
b730: 20 20 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 Z*N byt
b740: 65 73 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c es in size shall
b750: 20 63 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 cause S to be u
b760: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 sed by the.**
b770: 20 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 [scratch
b780: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b790: 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 ] for as many as
b7a0: 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 N simulataneous
b7b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c .** all
b7c0: 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 ocations each of
b7d0: 20 73 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b size Z..**.** {
b7e0: 48 31 34 31 35 33 7d 20 41 20 73 75 63 63 65 73 H14153} A succes
b7f0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
b800: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b810: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
b820: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 ATCH],S,Z,N).**
b830: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 53 where S
b840: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
b850: 65 72 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 er shall disable
b860: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
b870: 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 [scratch memory
b880: 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a allocator]..**.
b890: 2a 2a 20 7b 48 31 34 31 35 36 7d 20 41 20 73 75 ** {H14156} A su
b8a0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
b8b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
b8c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b8d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
b8e0: 45 43 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a ECACHE],S,Z,N).*
b8f0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 * where
b900: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e Z and N are non
b910: 2d 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 -negative intege
b920: 72 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 rs and .**
b930: 20 20 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 S is a point
b940: 65 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 er to an aligned
b950: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e memory buffer n
b960: 6f 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 ot less than.**
b970: 20 20 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 Z*N byt
b980: 65 73 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c es in size shall
b990: 20 63 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 cause S to be u
b9a0: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 sed by the.**
b9b0: 20 20 20 20 20 20 20 5b 70 61 67 65 63 61 63 68 [pagecach
b9c0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
b9d0: 6f 72 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 or] for as many
b9e0: 61 73 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f as N simulataneo
b9f0: 75 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 us.** a
ba00: 6c 6c 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20 llocations each
ba10: 6f 66 20 73 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a of size Z..**.**
ba20: 20 7b 48 31 34 31 35 39 7d 20 41 20 73 75 63 63 {H14159} A succ
ba30: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a essful call to.*
ba40: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
ba50: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
ba60: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
ba70: 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 ACHE],S,Z,N).**
ba80: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 53 where S
ba90: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
baa0: 65 72 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 er shall disable
bab0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
bac0: 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f [pagecache memo
bad0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a ry allocator]..*
bae0: 2a 0a 2a 2a 20 7b 48 31 34 31 36 32 7d 20 41 20 *.** {H14162} A
baf0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
bb00: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
bb10: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ig]([SQLITE_CONF
bb20: 49 47 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a IG_HEAP],H,Z,N).
bb30: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 ** wher
bb40: 65 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f e Z and N are no
bb50: 6e 2d 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 n-negative integ
bb60: 65 72 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 ers and .**
bb70: 20 20 20 20 20 48 20 69 73 20 61 20 70 6f 69 6e H is a poin
bb80: 74 65 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 ter to an aligne
bb90: 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 d memory buffer
bba0: 6e 6f 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a not less than.**
bbb0: 20 20 20 20 20 20 20 20 20 20 5a 20 62 79 74 65 Z byte
bbc0: 73 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 s in size shall
bbd0: 65 6e 61 62 6c 65 20 74 68 65 20 5b 6d 65 6d 73 enable the [mems
bbe0: 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ys5] memory allo
bbf0: 63 61 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 cator.**
bc00: 20 20 61 6e 64 20 63 61 75 73 65 20 69 74 20 74 and cause it t
bc10: 6f 20 75 73 65 20 62 75 66 66 65 72 20 53 20 61 o use buffer S a
bc20: 73 20 69 74 73 20 6d 65 6d 6f 72 79 20 73 6f 75 s its memory sou
bc30: 72 63 65 20 61 6e 64 20 74 6f 20 75 73 65 0a 2a rce and to use.*
bc40: 2a 20 20 20 20 20 20 20 20 20 20 61 20 6d 69 6e * a min
bc50: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
bc60: 73 69 7a 65 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a size of N..**.**
bc70: 20 7b 48 31 34 31 36 35 7d 20 41 20 73 75 63 63 {H14165} A succ
bc80: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
bc90: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
bca0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 [SQLITE_CONFIG_H
bcb0: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 EAP],H,Z,N).**
bcc0: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 48 20 where H
bcd0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
bce0: 72 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 r shall disable
bcf0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
bd00: 5b 6d 65 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79 [memsys5] memory
bd10: 20 61 6c 6c 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a allocator..**.*
bd20: 2a 20 7b 48 31 34 31 36 38 7d 20 41 20 73 75 63 * {H14168} A suc
bd30: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
bd40: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
bd50: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
bd60: 4c 4f 4f 4b 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a LOOKASIDE],Z,N).
bd70: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
bd80: 6c 20 63 61 75 73 65 20 74 68 65 20 64 65 66 61 l cause the defa
bd90: 75 6c 74 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d ult [lookaside m
bda0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
bdb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
bdc0: 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 6e * for n
bdd0: 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ew [database con
bde0: 6e 65 63 74 69 6f 6e 73 5d 20 74 6f 20 62 65 20 nections] to be
bdf0: 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 N slots of Z byt
be00: 65 73 20 65 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 es each..*/.SQLI
be10: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
be20: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 int sqlite3_conf
be30: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
be40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
be50: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
be60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b e connections {
be70: 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e H14200} <S20000>
be80: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
be90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
bea0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
beb0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
bec0: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 to make configu
bed0: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
bee0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 s to a [database
bef0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
bf00: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 he interface is
bf10: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 similar to.** [s
bf20: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
bf30: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
bf40: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 changes apply t
bf50: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 o a single.** [d
bf60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
bf70: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 on] (specified i
bf80: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
bf90: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 ment). The.** s
bfa0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
bfb0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e () interface can
bfc0: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d only be used im
bfd0: 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a mediately after.
bfe0: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
bff0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 connection is cr
c000: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c eated using [sql
c010: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a ite3_open()],.**
c020: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
c030: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 ()], or [sqlite3
c040: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a _open_v2()]. .*
c050: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
c060: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
c070: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c te3_db_config(D,
c080: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a V,...) is the.*
c090: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
c0a0: 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 verb - an intege
c0b0: 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 r code that indi
c0c0: 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 cates what.** as
c0d0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
c0e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
c0f0: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
c100: 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e gured..** The on
c110: 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 ly choice for th
c120: 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c is value is [SQL
c130: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
c140: 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 KASIDE]..** New
c150: 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 verbs are likely
c160: 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 to be added in
c170: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
c180: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 of SQLite..** Ad
c190: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
c1a0: 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 ts depend on the
c1b0: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 verb..**.** INV
c1c0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
c1d0: 48 31 34 32 30 33 7d 20 41 20 63 61 6c 6c 20 74 H14203} A call t
c1e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
c1f0: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 nfig(D,V,...)] s
c200: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c hall return [SQL
c210: 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 ITE_OK].**
c220: 20 20 20 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 if and only
c230: 69 66 20 74 68 65 20 63 61 6c 6c 20 69 73 20 73 if the call is s
c240: 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a uccessful..**.**
c250: 20 7b 48 31 34 32 30 36 7d 20 49 66 20 6f 6e 65 {H14206} If one
c260: 20 6f 72 20 6d 6f 72 65 20 73 6c 6f 74 73 20 6f or more slots o
c270: 66 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 f the [lookaside
c280: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
c290: 72 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 r] for.**
c2a0: 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e [database con
c2b0: 6e 65 63 74 69 6f 6e 5d 20 44 20 61 72 65 20 69 nection] D are i
c2c0: 6e 20 75 73 65 2c 20 74 68 65 6e 20 61 20 63 61 n use, then a ca
c2d0: 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ll to.**
c2e0: 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f [sqlite3_db_co
c2f0: 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f nfig](D,[SQLITE_
c300: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
c310: 44 45 5d 2c 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a DE],...) shall.*
c320: 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 20 * fail
c330: 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f with an [SQLITE_
c340: 42 55 53 59 5d 20 72 65 74 75 72 6e 20 63 6f 64 BUSY] return cod
c350: 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 e..**.** {H14209
c360: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
c370: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 all to .**
c380: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f [sqlite3_db_
c390: 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 config](D,[SQLIT
c3a0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
c3b0: 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 SIDE],B,Z,N) whe
c3c0: 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 re.** D
c3d0: 20 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 is an open [dat
c3e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
c3f0: 5d 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 ] and Z and N ar
c400: 65 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 e positive.**
c410: 20 20 20 20 20 20 20 69 6e 74 65 67 65 72 73 20 integers
c420: 61 6e 64 20 42 20 69 73 20 61 6e 20 61 6c 69 67 and B is an alig
c430: 6e 65 64 20 62 75 66 66 65 72 20 61 74 20 6c 65 ned buffer at le
c440: 61 73 74 20 5a 2a 4e 20 62 79 74 65 73 20 69 6e ast Z*N bytes in
c450: 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 size.**
c460: 20 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 shall cause th
c470: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d e [lookaside mem
c480: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 ory allocator] f
c490: 6f 72 20 44 20 74 6f 20 75 73 65 20 62 75 66 66 or D to use buff
c4a0: 65 72 20 42 20 0a 2a 2a 20 20 20 20 20 20 20 20 er B .**
c4b0: 20 20 77 69 74 68 20 4e 20 73 6c 6f 74 73 20 6f with N slots o
c4c0: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a f Z bytes each..
c4d0: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 32 7d 20 41 **.** {H14212} A
c4e0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
c4f0: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 to .**
c500: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
c510: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 fig](D,[SQLITE_D
c520: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
c530: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a E],B,Z,N) where.
c540: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 ** D is
c550: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 an open [databa
c560: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
c570: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 nd Z and N are p
c580: 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 ositive.**
c590: 20 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 integers and
c5a0: 20 42 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 B is NULL point
c5b0: 65 72 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 er shall cause t
c5c0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
c5d0: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
c5e0: 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 allocator] for
c5f0: 44 20 74 6f 20 61 20 6f 62 74 61 69 6e 20 5a 2a D to a obtain Z*
c600: 4e 20 62 79 74 65 20 62 75 66 66 65 72 0a 2a 2a N byte buffer.**
c610: 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 from t
c620: 68 65 20 70 72 69 6d 61 72 79 20 6d 65 6d 6f 72 he primary memor
c630: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 61 6e 64 20 y allocator and
c640: 75 73 65 20 74 68 61 74 20 62 75 66 66 65 72 0a use that buffer.
c650: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 ** with
c660: 20 4e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 6c 6f N lookaside slo
c670: 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61 ts of Z bytes ea
c680: 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 ch..**.** {H1421
c690: 35 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 5} A successful
c6a0: 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 call to .**
c6b0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 [sqlite3_db
c6c0: 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 _config](D,[SQLI
c6d0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
c6e0: 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 ASIDE],B,Z,N) wh
c6f0: 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ere.**
c700: 44 20 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 D is an open [da
c710: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c720: 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 n] and Z and N a
c730: 72 65 20 7a 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a re zero shall.**
c740: 20 20 20 20 20 20 20 20 20 20 64 69 73 61 62 6c disabl
c750: 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 e the [lookaside
c760: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
c770: 72 5d 20 66 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a r] for D..**.**.
c780: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
c790: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
c7a0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c e3_db_config(sql
c7b0: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e ite3*, int op, .
c7c0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
c7d0: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
c7e0: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ocation Routines
c7f0: 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 {H10155} <S2012
c800: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
c810: 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 AL.**.** An inst
c820: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
c830: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
c840: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
c850: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 n SQLite.** and
c860: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
c870: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
c880: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ines..**.** This
c890: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 object is used
c8a0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 in only one plac
c8b0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
c8c0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 interface..** A
c8d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
c8e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
c8f0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 bject is the arg
c900: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c ument to.** [sql
c910: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
c920: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 hen the configur
c930: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a ation option is.
c940: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
c950: 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 G_MALLOC]. By c
c960: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 reating an insta
c970: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
c980: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e ct.** and passin
c990: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
c9a0: 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e _config()] durin
c9b0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c g configuration,
c9c0: 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 an.** applicati
c9d0: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 on can specify a
c9e0: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 n alternative me
c9f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
ca00: 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 subsystem.** for
ca10: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 SQLite to use f
ca20: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 or all of its dy
ca30: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 namic memory nee
ca40: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ds..**.** Note t
ca50: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 hat SQLite comes
ca60: 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e with a built-in
ca70: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
ca80: 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 r that is.** per
ca90: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 fectly adequate
caa0: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c for the overwhel
cab0: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 ming majority of
cac0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
cad0: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f and that this o
cae0: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 bject is only us
caf0: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d eful to a tiny m
cb00: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 inority of appli
cb10: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 cations.** with
cb20: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f specialized memo
cb30: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
cb40: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 quirements. Thi
cb50: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 s object is.** a
cb60: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 lso used during
cb70: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 testing of SQLit
cb80: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 e in order to sp
cb90: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
cba0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
cbb0: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 llocator that si
cbc0: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f mulates memory o
cbd0: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e ut-of-memory con
cbe0: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 ditions in.** or
cbf0: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 der to verify th
cc00: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 at SQLite recove
cc10: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 rs gracefully fr
cc20: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 om such.** condi
cc30: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tions..**.** The
cc40: 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c xMalloc, xFree,
cc50: 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 and xRealloc me
cc60: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 thods must work
cc70: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c like the.** mall
cc80: 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e oc(), free(), an
cc90: 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 d realloc() func
cca0: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 tions from the s
ccb0: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e tandard library.
ccc0: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f .**.** xSize sho
ccd0: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 uld return the a
cce0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 llocated size of
ccf0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
cd00: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 tion.** previous
cd10: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ly obtained from
cd20: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 xMalloc or xRea
cd30: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 lloc. The alloc
cd40: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 ated size.** is
cd50: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 always at least
cd60: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 as big as the re
cd70: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 quested size but
cd80: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a may be larger..
cd90: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 **.** The xRound
cda0: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e up method return
cdb0: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 s what would be
cdc0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 the allocated si
cdd0: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 ze of.** a memor
cde0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 y allocation giv
cdf0: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 en a particular
ce00: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 requested size.
ce10: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 Most memory.**
ce20: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
ce30: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 up memory alloc
ce40: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 ations at least
ce50: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 to the next mult
ce60: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 iple.** of 8. S
ce70: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 ome allocators r
ce80: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 ound up to a lar
ce90: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 ger multiple or
cea0: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e to a power of 2.
ceb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
cec0: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
ced0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
cee0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 llocator. (For
cef0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
cf00: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
cf10: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
cf20: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
cf30: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
cf40: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
cf50: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
cf60: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
cf70: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
cf80: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
cf90: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
cfa0: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
cfb0: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
cfc0: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
cfd0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
cfe0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
cff0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
d000: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
d010: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
d020: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
d030: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
d040: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d hods sqlite3_mem
d050: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
d060: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
d070: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 hods {. void *(
d080: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 *xMalloc)(int);
d090: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 /* Memor
d0a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e y allocation fun
d0b0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ction */. void
d0c0: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b (*xFree)(void*);
d0d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 /* Fre
d0e0: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 e a prior alloca
d0f0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
d100: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 (*xRealloc)(void
d110: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 *,int); /* Resi
d120: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e ze an allocation
d130: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a */. int (*xSiz
d140: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
d150: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 /* Return t
d160: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c he size of an al
d170: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e location */. in
d180: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e t (*xRoundup)(in
d190: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 t); /*
d1a0: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 Round up request
d1b0: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 size to allocat
d1c0: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e ion size */. in
d1d0: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a t (*xInit)(void*
d1e0: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ); /*
d1f0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d Initialize the m
d200: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
d210: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 */. void (*xShu
d220: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 tdown)(void*);
d230: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c /* Deinitial
d240: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ize the memory a
d250: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f llocator */. vo
d260: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
d270: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
d280: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 Argument to xIni
d290: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 t() and xShutdow
d2a0: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a n() */.};../*.**
d2b0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
d2c0: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 guration Options
d2d0: 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 {H10160} <S2000
d2e0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
d2f0: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 AL.**.** These c
d300: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
d310: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
d320: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
d330: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
d340: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
d350: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
d360: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
d370: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
d380: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
d390: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
d3a0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
d3b0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
d3c0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
d3d0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
d3e0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
d3f0: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
d400: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
d410: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
d420: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
d430: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
d440: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
d450: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
d460: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
d470: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b l worked. The [
d480: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
d490: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
d4a0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
d4b0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
d4c0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
d4d0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
d4e0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
d4f0: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
d500: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
d510: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
d520: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
d530: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
d540: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
d550: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
d560: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 option. This op
d570: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a tion disables.**
d580: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e all mutexing an
d590: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e d puts SQLite in
d5a0: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 to a mode where
d5b0: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 it can only be u
d5c0: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 sed.** by a sing
d5d0: 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a le thread.</dd>.
d5e0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
d5f0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
d600: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
d610: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
d620: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
d630: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 ption. This opt
d640: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 ion disables.**
d650: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 mutexing on [dat
d660: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d670: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
d680: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 statement] objec
d690: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ts..** The appli
d6a0: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e cation is respon
d6b0: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c sible for serial
d6c0: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a izing access to.
d6d0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
d6e0: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 nections] and [p
d6f0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
d700: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 ts]. But other
d710: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 mutexes.** are e
d720: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 nabled so that S
d730: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 QLite will be sa
d740: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d fe to use in a m
d750: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a ulti-threaded.**
d760: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 environment as
d770: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 long as no two t
d780: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 hreads attempt t
d790: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a o use the same.*
d7a0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
d7b0: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 ection] at the s
d7c0: 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74 ame time. See t
d7d0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
d7e0: 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 de].** documenta
d7f0: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
d800: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
d810: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
d820: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
d830: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a RIALIZED</dt>.**
d840: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
d850: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
d860: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 his option. Thi
d870: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 s option enables
d880: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 .** all mutexes
d890: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 including the re
d8a0: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 cursive.** mutex
d8b0: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 es on [database
d8c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 connection] and
d8d0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
d8e0: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a ent] objects..**
d8f0: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 In this mode (w
d900: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 hich is the defa
d910: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 ult when SQLite
d920: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
d930: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
d940: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 ADSAFE=1]) the S
d950: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
d960: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c ll itself serial
d970: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ize access.** to
d980: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
d990: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
d9a0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
d9b0: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a ] so that the.**
d9c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 application is
d9d0: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 free to use the
d9e0: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
d9f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 onnection] or th
da00: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 e.** same [prepa
da10: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
da20: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 n different thre
da30: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
da40: 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 time..** See the
da50: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
da60: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
da70: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
da80: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e nformation.</dd>
da90: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
daa0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c E_CONFIG_MALLOC<
dab0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
dac0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
dad0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
dae0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
daf0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
db00: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
db10: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
db20: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
db30: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 e argument speci
db40: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 fies.** alternat
db50: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 ive low-level me
db60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
db70: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 routines to be u
db80: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a sed in place of.
db90: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ** the memory al
dba0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
dbb0: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
dbc0: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ite.</dd>.**.**
dbd0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
dbe0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e G_GETMALLOC</dt>
dbf0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
dc00: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
dc10: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
dc20: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
dc30: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
dc40: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
dc50: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
dc60: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 ructure. The [s
dc70: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
dc80: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
dc90: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
dca0: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
dcb0: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c fined memory all
dcc0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
dcd0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ..** This option
dce0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
dcf0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
dd00: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
dd10: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
dd20: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
dd30: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f r that simulatio
dd40: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ns memory alloca
dd50: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a tion failure or.
dd60: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 ** tracks memory
dd70: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d usage, for exam
dd80: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ple.</dd>.**.**
dd90: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
dda0: 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e G_MEMSTATUS</dt>
ddb0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
ddc0: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 ion takes single
ddd0: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 argument of typ
dde0: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 e int, interpret
ddf0: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c ed as a .** bool
de00: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c ean, which enabl
de10: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
de20: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 he collection of
de30: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
de40: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 on .** statistic
de50: 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 s. When disabled
de60: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 , the following
de70: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
de80: 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e s become .** non
de90: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a -operational:.**
dea0: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 <ul>.** <li
deb0: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
dec0: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c y_used()].** <
ded0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
dee0: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
def0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
df00: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
df10: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e mit()].** <li>
df20: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
df30: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a ()].** </ul>.*
df40: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 * </dd>.**.** <d
df50: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
df60: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 SCRATCH</dt>.**
df70: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
df80: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
df90: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
dfa0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
dfb0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 use for.** scra
dfc0: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 tch memory. The
dfd0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
dfe0: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 uments: A point
dff0: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
e000: 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 , the.** size of
e010: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62 75 each scratch bu
e020: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 ffer (sz), and t
e030: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 he number of buf
e040: 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 fers (N). The s
e050: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 z.** argument mu
e060: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 st be a multiple
e070: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 of 16. The sz p
e080: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 arameter should
e090: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a be a few bytes.*
e0a0: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 * larger than th
e0b0: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 e actual scratch
e0c0: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 space required
e0d0: 64 75 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 due internal ove
e0e0: 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 rhead..** The fi
e0f0: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 rst.** argument
e100: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 should point to
e110: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 an allocation of
e120: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 at least sz*N b
e130: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a ytes of memory..
e140: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 ** SQLite will u
e150: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 se no more than
e160: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 one scratch buff
e170: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 er at once per t
e180: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 hread, so.** N s
e190: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 hould be set to
e1a0: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 the expected max
e1b0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 imum number of t
e1c0: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a hreads. The sz.
e1d0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f ** parameter sho
e1e0: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 uld be 6 times t
e1f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c he size of the l
e200: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 argest database
e210: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 page size..** Sc
e220: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 ratch buffers ar
e230: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f e used as part o
e240: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 f the btree bala
e250: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 nce operation.
e260: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 If.** The btree
e270: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 balancer needs a
e280: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 dditional memory
e290: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
e2a0: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 provided by.** s
e2b0: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f cratch buffers o
e2c0: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 r if no scratch
e2d0: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 buffer space is
e2e0: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 specified, then
e2f0: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 SQLite.** goes t
e300: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
e310: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 c()] to obtain t
e320: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 he memory it nee
e330: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ds.</dd>.**.** <
e340: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
e350: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a _PAGECACHE</dt>.
e360: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
e370: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
e380: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
e390: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
e3a0: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 can use for.** t
e3b0: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
e3c0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 cache with the
e3d0: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 default page cac
e3e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e he implemenation
e3f0: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 . .** This conf
e400: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 iguration should
e410: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 not be used if
e420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
e430: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 efine page.** ca
e440: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
e450: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 on is loaded usi
e460: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f ng the SQLITE_CO
e470: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 NFIG_PCACHE opti
e480: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 on..** There are
e490: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
e4a0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a to this option:
e4b0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 A pointer to th
e4c0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 e.** memory, the
e4d0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 size of each pa
e4e0: 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 ge buffer (sz),
e4f0: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f and the number o
e500: 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 f pages (N)..**
e510: 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 The sz argument
e520: 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72 20 must be a power
e530: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 of two between 5
e540: 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54 12 and 32768. T
e550: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 he first.** argu
e560: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e ment should poin
e570: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 t to an allocati
e580: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 on of at least s
e590: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d z*N bytes of mem
e5a0: 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 ory..** SQLite w
e5b0: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f ill use the memo
e5c0: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 ry provided by t
e5d0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
e5e0: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 t to satisfy its
e5f0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 .** memory needs
e600: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e for the first N
e610: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 pages that it a
e620: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49 dds to cache. I
e630: 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 f additional.**
e640: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
e650: 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f y is needed beyo
e660: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
e670: 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 ded by this opti
e680: 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 on, then.** SQLi
e690: 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 te goes to [sqli
e6a0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f te3_malloc()] fo
e6b0: 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c r the additional
e6c0: 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a storage space..
e6d0: 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** The implement
e6e0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 ation might use
e6f0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
e700: 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20 he N buffers to
e710: 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 hold .** memory
e720: 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 accounting infor
e730: 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a mation. </dd>.**
e740: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
e750: 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a ONFIG_HEAP</dt>.
e760: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
e770: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
e780: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
e790: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
e7a0: 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 will use.** for
e7b0: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
e7c0: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ic memory alloca
e7d0: 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e tion needs beyon
e7e0: 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 d those provided
e7f0: 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 .** for by [SQLI
e800: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
e810: 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 H] and [SQLITE_C
e820: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
e830: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 ..** There are t
e840: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
e850: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
e860: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d memory, the num
e870: 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 ber of.** bytes
e880: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
e890: 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
e8a0: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
e8b0: 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 size. If.** th
e8c0: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
e8d0: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
e8e0: 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
e8f0: 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
e900: 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
e910: 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
e920: 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
e930: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
e940: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
e950: 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
e960: 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
e970: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
e980: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 IG_MALLOC]. If
e990: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f the.** memory po
e9a0: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
e9b0: 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 L and either [SQ
e9c0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 LITE_ENABLE_MEMS
e9d0: 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 YS3] or.** [SQLI
e9e0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
e9f0: 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 5] are defined,
ea00: 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 then the alterna
ea10: 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 tive memory.** a
ea20: 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 llocator is enga
ea30: 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c ged to handle al
ea40: 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d l of SQLites mem
ea50: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
ea60: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a eeds.</dd>.**.**
ea70: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
ea80: 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a IG_MUTEX</dt>.**
ea90: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
eaa0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
eab0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
eac0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
ead0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
eae0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
eaf0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
eb00: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 ucture. The arg
eb10: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
eb20: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
eb30: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 ow-level mutex r
eb40: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
eb50: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 ed in place.** t
eb60: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 he mutex routine
eb70: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
eb80: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ite.</dd>.**.**
eb90: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
eba0: 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a G_GETMUTEX</dt>.
ebb0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
ebc0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
ebd0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
ebe0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
ebf0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
ec00: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
ec10: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
ec20: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
ec30: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
ec40: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
ec50: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
ec60: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
ec70: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
ec80: 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 x routines..** T
ec90: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
eca0: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
ecb0: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
ecc0: 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a utex allocation.
ecd0: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
ece0: 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 a wrapper used
ecf0: 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 to track mutex u
ed00: 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d sage for perform
ed10: 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e ance.** profilin
ed20: 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f g or testing, fo
ed30: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a r example.</dd>.
ed40: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
ed50: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
ed60: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
ed70: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
ed80: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 two arguments th
ed90: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 at determine the
eda0: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f default.** memo
edb0: 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f ry allcation loo
edc0: 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 kaside optimizat
edd0: 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 ion. The first
ede0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a argument is the.
edf0: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 ** size of each
ee00: 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
ee10: 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 slot and the se
ee20: 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 cond is the numb
ee30: 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 er of.** slots a
ee40: 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 llocated to each
ee50: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
ee60: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
ee70: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
ee80: 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a IG_PCACHE</dt>.*
ee90: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
eea0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
eeb0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
eec0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a is a pointer to.
eed0: 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ** an [sqlite3_p
eee0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f cache_methods] o
eef0: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a bject. This obj
ef00: 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 ect specifies th
ef10: 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 e interface.** t
ef20: 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 o a custom page
ef30: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
ef40: 74 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 tion. SQLite ma
ef50: 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
ef60: 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 e.** object and
ef70: 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 uses it for page
ef80: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c cache memory al
ef90: 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a locations.</dd>.
efa0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
efb0: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
efc0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
efd0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
efe0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
eff0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
f000: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 nter to an.** [s
f010: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
f020: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 thods] object.
f030: 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 SQLite copies of
f040: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
f050: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
f060: 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 mentation into t
f070: 68 61 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e hat object.</dd>
f080: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a .**.** </dl>.*/.
f090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
f0a0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
f0b0: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f AD 1 /* nil */
f0c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f0d0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
f0e0: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a AD 2 /* nil *
f0f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
f100: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
f110: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 ED 3 /* nil
f120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f130: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
f140: 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 4 /* sql
f150: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
f160: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
f170: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
f180: 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 LLOC 5 /* s
f190: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
f1a0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
f1b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
f1c0: 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a ATCH 6 /*
f1d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
f1e0: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
f1f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
f200: 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 AGECACHE 7
f210: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
f220: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
f230: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
f240: 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 _HEAP 8
f250: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
f260: 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a nByte, int min *
f270: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
f280: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
f290: 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c S 9 /* bool
f2a0: 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ean */.#define S
f2b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
f2c0: 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a EX 10 /*
f2d0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
f2e0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
f2f0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
f300: 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 _GETMUTEX 11
f310: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
f320: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f ex_methods* */./
f330: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c * previously SQL
f340: 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b ITE_CONFIG_CHUNK
f350: 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 ALLOC 12 which i
f360: 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f s now unused. */
f370: 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .#define SQLITE
f380: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
f390: 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 E 13 /* int
f3a0: 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
f3b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
f3c0: 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a CHE 14 /*
f3d0: 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
f3e0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
f3f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
f400: 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 G_GETPCACHE 1
f410: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 5 /* sqlite3_pc
f420: 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f ache_methods* */
f430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
f440: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 : Configuration
f450: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d Options {H10170}
f460: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 <S20000>.** EXP
f470: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
f480: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
f490: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
f4a0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
f4b0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
f4c0: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
f4d0: 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
f4e0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
f4f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
f500: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
f510: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
f520: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
f530: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
f540: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
f550: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
f560: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
f570: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
f580: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
f590: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
f5a0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
f5b0: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
f5c0: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
f5d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
f5e0: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
f5f0: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
f600: 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 worked. The [sq
f610: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
f620: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c )] interface wil
f630: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f l return a.** no
f640: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
f650: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 de] if a discont
f660: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f inued or unsuppo
f670: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 rted configurati
f680: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 on option.** is
f690: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c invoked..**.** <
f6a0: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 dl>.** <dt>SQLIT
f6b0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
f6c0: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIDE</dt>.** <dd
f6d0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
f6e0: 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f es three additio
f6f0: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 nal arguments th
f700: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 at determine the
f710: 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 .** [lookaside
f720: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
f730: 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 ] configuration
f740: 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 for the [databas
f750: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
f760: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
f770: 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 ment (the third
f780: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
f790: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
f7a0: 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 )] is a.** point
f7b0: 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 er to a memory b
f7c0: 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 uffer to use for
f7d0: 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
f7e0: 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a y. The first.**
f7f0: 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 argument may be
f800: 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 NULL in which c
f810: 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ase SQLite will
f820: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f 6f allocate the loo
f830: 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65 72 kaside.** buffer
f840: 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 itself using [s
f850: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
f860: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
f870: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
f880: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
f890: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
f8a0: 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69 72 lot and the thir
f8b0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
f8c0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
f8d0: 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 lots. The size
f8e0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e of the buffer in
f8f0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
f900: 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 ent must be grea
f910: 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 ter than.** or e
f920: 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 qual to the prod
f930: 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e uct of the secon
f940: 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 d and third argu
f950: 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ments.</dd>.**.*
f960: 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
f970: 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
f980: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
f990: 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 1001 /* void* i
f9a0: 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a nt int */.../*.*
f9b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
f9c0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
f9d0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
f9e0: 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 des {H12200} <S1
f9f0: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0700>.**.** The
fa00: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
fa10: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
fa20: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
fa30: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
fa40: 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
fa50: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
fa60: 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 re of SQLite. Th
fa70: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
fa80: 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 t.** codes are d
fa90: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
faa0: 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 lt for historica
fab0: 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 l compatibility
fac0: 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a considerations..
fad0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
fae0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d :.**.** {H12201}
faf0: 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 Each new [datab
fb00: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
fb10: 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a shall have the.*
fb20: 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 * [exte
fb30: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
fb40: 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61 62 s] feature disab
fb50: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
fb60: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54 **.** {H12202} T
fb70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 he [sqlite3_exte
fb80: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
fb90: 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 s(D,F)] interfac
fba0: 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a e shall enable.*
fbb0: 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 * [exte
fbc0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
fbd0: 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74 s] for the [dat
fbe0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
fbf0: 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ] D.**
fc00: 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 if the F paramet
fc10: 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 er is true, or d
fc20: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 isable them if F
fc30: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e is false..*/.in
fc40: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
fc50: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
fc60: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e sqlite3*, int on
fc70: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 off);../*.** CAP
fc80: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 I3REF: Last Inse
fc90: 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 rt Rowid {H12220
fca0: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
fcb0: 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 Each entry in a
fcc0: 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 n SQLite table h
fcd0: 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
fce0: 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
fcf0: 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
fd00: 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 the "rowid". The
fd10: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 rowid is always
fd20: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 available.** as
fd30: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 an undeclared c
fd40: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 olumn named ROWI
fd50: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 D, OID, or _ROWI
fd60: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 D_ as long as th
fd70: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 ose.** names are
fd80: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 not also used b
fd90: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 y explicitly dec
fda0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 lared columns. I
fdb0: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 f.** the table h
fdc0: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 as a column of t
fdd0: 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d ype INTEGER PRIM
fde0: 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 ARY KEY then tha
fdf0: 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 t column.** is a
fe00: 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 nother alias for
fe10: 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a the rowid..**.*
fe20: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
fe30: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 eturns the rowid
fe40: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 of the most rec
fe50: 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ent.** successfu
fe60: 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
fe70: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f the database fro
fe80: 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 m the [database
fe90: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 connection].** i
fea0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
feb0: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 ment. If no suc
fec0: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
fed0: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
fee0: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 ccurred on that
fef0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
ff00: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
ff10: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 urned..**.** If
ff20: 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 an [INSERT] occu
ff30: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 rs within a trig
ff40: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f ger, then the ro
ff50: 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65 72 wid of the inser
ff60: 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 ted.** row is re
ff70: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 turned by this r
ff80: 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 outine as long a
ff90: 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 s the trigger is
ffa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 running..** But
ffb0: 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 once the trigge
ffc0: 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 r terminates, th
ffd0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
ffe0: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
fff0: 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 .** reverts to t
10000 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e he last value in
10010 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 serted before th
10020 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e e trigger fired.
10030 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 .**.** An [INSER
10040 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 T] that fails du
10050 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e e to a constrain
10060 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e t violation is n
10070 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 ot a.** successf
10080 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 ul [INSERT] and
10090 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
100a0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
100b0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f ed by this.** ro
100c0 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 utine. Thus INS
100d0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 ERT OR FAIL, INS
100e0 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 ERT OR IGNORE, I
100f0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 NSERT OR ROLLBAC
10100 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 K,.** and INSERT
10110 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e OR ABORT make n
10120 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 o changes to the
10130 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
10140 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
10150 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 when their inse
10160 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 rtion fails. Wh
10170 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 en INSERT OR REP
10180 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 LACE.** encounte
10190 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 rs a constraint
101a0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f violation, it do
101b0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 es not fail. Th
101c0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 e.** INSERT cont
101d0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 inues to complet
101e0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 ion after deleti
101f0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 ng rows that cau
10200 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 sed.** the const
10210 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f raint problem so
10220 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
10230 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 CE will always c
10240 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 hange.** the ret
10250 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
10260 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
10270 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f ** For the purpo
10280 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ses of this rout
10290 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d ine, an [INSERT]
102a0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 is considered t
102b0 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 o.** be successf
102c0 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 ul even if it is
102d0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f subsequently ro
102e0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
102f0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
10300 2a 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 ** {H12221} The
10310 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
10320 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 sert_rowid()] fu
10330 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 nction shall ret
10340 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a urn the rowid.**
10350 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
10360 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 most recent suc
10370 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
10380 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 performed on th
10390 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e same.**
103a0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e [database con
103b0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 nection] and wit
103c0 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 hin the same or
103d0 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 higher level.**
103e0 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72 trigger
103f0 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 context, or zer
10400 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 20 o if there have
10410 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 been no qualifyi
10420 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ng.** [
10430 49 4e 53 45 52 54 5d 20 73 74 61 74 65 6d 65 6e INSERT] statemen
10440 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 ts..**.** {H1222
10450 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
10460 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
10470 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 d()] function sh
10480 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 0a 2a all return the.*
10490 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 * same
104a0 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 value when calle
104b0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
104c0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a trigger context.
104d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 ** imme
104e0 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 diately before a
104f0 6e 64 20 61 66 74 65 72 20 61 20 5b 52 4f 4c 4c nd after a [ROLL
10500 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 BACK]..**.** ASS
10510 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
10520 7b 41 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 {A12232} If a se
10530 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 parate thread pe
10540 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e rforms a new [IN
10550 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d SERT] on the sam
10560 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 e.** da
10570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10580 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c n while the [sql
10590 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
105a0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 _rowid()].**
105b0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 function i
105c0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 s running and th
105d0 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c us changes the l
105e0 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 ast insert rowid
105f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
10600 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
10610 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
10620 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
10630 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 wid()] is.**
10640 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 unpredicta
10650 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f ble and might no
10660 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 t equal either t
10670 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 he old or the ne
10680 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 w.** la
10690 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e st insert rowid.
106a0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
106b0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
106c0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
106d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
106e0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
106f0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
10700 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 Modified {H1224
10710 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S10600>.**.*
10720 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
10730 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
10740 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 er of database r
10750 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 ows that were ch
10760 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 anged.** or inse
10770 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 rted or deleted
10780 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 by the most rece
10790 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 ntly completed S
107a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL statement.**
107b0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
107c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
107d0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 cified by the fi
107e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a rst parameter..*
107f0 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 * Only changes t
10800 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 hat are directly
10810 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
10820 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 e [INSERT], [UPD
10830 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c ATE],.** or [DEL
10840 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ETE] statement a
10850 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 re counted. Aux
10860 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 iliary changes c
10870 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 aused by.** trig
10880 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 gers are not cou
10890 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 nted. Use the [s
108a0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
108b0 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e nges()] function
108c0 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 .** to find the
108d0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 total number of
108e0 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e changes includin
108f0 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 g changes caused
10900 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a by triggers..**
10910 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 .** A "row chang
10920 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 e" is a change t
10930 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f o a single row o
10940 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 f a single table
10950 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e .** caused by an
10960 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c INSERT, DELETE,
10970 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 or UPDATE state
10980 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 ment. Rows that
10990 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 .** are changed
109a0 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 as side effects
109b0 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 of REPLACE const
109c0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
109d0 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 ,.** rollback, A
109e0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
109f0 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 DROP TABLE, or
10a00 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
10a10 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
10a20 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
10a30 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a t row changes..*
10a40 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 *.** A "trigger
10a50 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 context" is a sc
10a60 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e ope of execution
10a70 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 that begins and
10a80 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 .** ends with th
10a90 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 e script of a tr
10aa0 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c igger. Most SQL
10ab0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a statements are.
10ac0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 ** evaluated out
10ad0 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 side of any trig
10ae0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 ger. This is th
10af0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a e "top level".**
10b00 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
10b10 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 . If a trigger
10b20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 fires from the t
10b30 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e op level, a.** n
10b40 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
10b50 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f xt is entered fo
10b60 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f r the duration o
10b70 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 f that one.** tr
10b80 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 igger. Subtrigg
10b90 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f ers create subco
10ba0 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 ntexts for their
10bb0 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a duration..**.**
10bc0 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 Calling [sqlite
10bd0 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 3_exec()] or [sq
10be0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
10bf0 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a cursively does.*
10c00 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e * not create a n
10c10 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
10c20 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 xt..**.** This f
10c30 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
10c40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 the number of di
10c50 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 rect row changes
10c60 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 in the.** most
10c70 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 recent INSERT, U
10c80 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
10c90 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
10ca0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 n the same.** tr
10cb0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a igger context..*
10cc0 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 *.** Thus, when
10cd0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
10ce0 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 top level, this
10cf0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
10d00 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
10d10 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 f changes in the
10d20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
10d30 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
10d40 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 DELETE.** that a
10d50 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 lso occurred at
10d60 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 the top level.
10d70 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 Within the body
10d80 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a of a trigger,.**
10d90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
10da0 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 nges() interface
10db0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 can be called t
10dc0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
10dd0 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 r of.** changes
10de0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
10df0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 ntly completed I
10e00 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
10e10 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 r DELETE.** stat
10e20 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
10e30 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d body of the sam
10e40 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f e trigger..** Ho
10e50 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 wever, the numbe
10e60 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 r returned does
10e70 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e not include chan
10e80 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 ges.** caused by
10e90 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e subtriggers sin
10ea0 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 ce those have th
10eb0 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e eir own context.
10ec0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d .**.** SQLite im
10ed0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d plements the com
10ee0 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f mand "DELETE FRO
10ef0 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 M table" without
10f00 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a a WHERE clause.
10f10 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 ** by dropping a
10f20 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 nd recreating th
10f30 65 20 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 e table. Doing
10f40 73 6f 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 so is much faste
10f50 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 r than going.**
10f60 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 through and dele
10f70 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 ting individual
10f80 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 elements from th
10f90 65 20 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 e table. Becaus
10fa0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 e of this.** opt
10fb0 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 imization, the d
10fc0 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c eletions in "DEL
10fd0 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 ETE FROM table"
10fe0 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e are not row chan
10ff0 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 ges and.** will
11000 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 not be counted b
11010 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 y the sqlite3_ch
11020 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 anges() or [sqli
11030 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
11040 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e s()].** function
11050 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 s, regardless of
11060 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
11070 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 lements that wer
11080 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 e originally.**
11090 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 in the table. T
110a0 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 o get an accurat
110b0 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e e count of the n
110c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 umber of rows de
110d0 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 leted, use.** "D
110e0 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
110f0 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 WHERE 1" instea
11100 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 d. Or recompile
11110 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 using the.** [S
11120 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 QLITE_OMIT_TRUNC
11130 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e ATE_OPTIMIZATION
11140 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
11150 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 ption to disable
11160 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 the.** optimiza
11170 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 tion on all quer
11180 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ies..**.** INVAR
11190 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
111a0 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2241} The [sqlit
111b0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 e3_changes()] fu
111c0 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 nction shall ret
111d0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
111e0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f f.** ro
111f0 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 w changes caused
11200 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
11210 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ent INSERT, UPDA
11220 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 TE,.**
11230 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
11240 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ent on the same
11250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11260 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ion and.**
11270 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 within the s
11280 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 ame or higher tr
11290 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f igger context, o
112a0 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 r zero if there
112b0 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 have.**
112c0 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 not been any qu
112d0 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 alifying row cha
112e0 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 nges..**.** {H12
112f0 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 243} Statements
11300 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c of the form "DEL
11310 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 ETE FROM tablena
11320 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 me" with no.**
11330 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c WHERE cl
11340 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 ause shall cause
11350 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
11360 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 s to.**
11370 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
11380 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a s()] to return z
11390 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 ero, regardless
113a0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
113b0 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 number of row
113c0 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 s originally in
113d0 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a the table..**.**
113e0 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
113f0 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 .** {A12252} If
11400 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
11410 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
11420 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
11430 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
11440 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c ** whil
11450 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
11460 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
11470 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
11480 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 returned.**
11490 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 is unpredic
114a0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
114b0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 aningful..*/.int
114c0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
114d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
114e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
114f0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
11500 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 s Modified {H122
11510 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 60} <S10600>.**.
11520 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
11530 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
11540 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 ber of row chang
11550 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 es caused by INS
11560 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f ERT,.** UPDATE o
11570 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
11580 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 nts since the [d
11590 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
115a0 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a on] was opened..
115b0 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 ** The count inc
115c0 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 ludes all change
115d0 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 s from all trigg
115e0 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f er contexts. Ho
115f0 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f wever,.** the co
11600 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
11610 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 lude changes use
11620 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 d to implement R
11630 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e EPLACE constrain
11640 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 ts,.** do rollba
11650 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f cks or ABORT pro
11660 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 cessing, or DROP
11670 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e table processin
11680 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 g..** The change
11690 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 s are counted as
116a0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 soon as the sta
116b0 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
116c0 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d s them is.** com
116d0 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 pleted (when the
116e0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c statement handl
116f0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b e is passed to [
11700 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
11710 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
11720 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a finalize()])..**
11730 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 .** SQLite imple
11740 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e ments the comman
11750 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 d "DELETE FROM t
11760 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 able" without a
11770 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 WHERE clause.**
11780 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 by dropping and
11790 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 recreating the t
117a0 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 able. (This is
117b0 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e much faster than
117c0 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 going.** throug
117d0 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 h and deleting i
117e0 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e ndividual elemen
117f0 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c ts from the tabl
11800 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 e.) Because of
11810 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 this.** optimiza
11820 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 tion, the deleti
11830 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 ons in "DELETE F
11840 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e ROM table" are n
11850 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 ot row changes a
11860 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 nd.** will not b
11870 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 e counted by the
11880 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
11890 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 () or [sqlite3_t
118a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a otal_changes()].
118b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 ** functions, re
118c0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
118d0 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e number of elemen
118e0 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 ts that were ori
118f0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 ginally.** in th
11900 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 e table. To get
11910 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 an accurate cou
11920 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 nt of the number
11930 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 of rows deleted
11940 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 , use.** "DELETE
11950 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 FROM table WHER
11960 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20 E 1" instead.
11970 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 Or recompile usi
11980 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ng the.** [SQLIT
11990 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f E_OMIT_TRUNCATE_
119a0 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f OPTIMIZATION] co
119b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
119c0 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 n to disable the
119d0 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e .** optimization
119e0 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e on all queries.
119f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
11a00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
11a10 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
11a20 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 e..**.** INVARIA
11a30 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 NTS:.**.** {H122
11a40 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 61} The [sqlite3
11a50 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
11a60 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f ] returns the to
11a70 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 tal number.**
11a80 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 of row ch
11a90 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
11aa0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
11ab0 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a and/or DELETE.**
11ac0 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d statem
11ad0 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 ents on the same
11ae0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11af0 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a ction], in any.*
11b00 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 * trigg
11b10 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 er context, sinc
11b20 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
11b30 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 onnection was cr
11b40 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 eated..**.** {H1
11b50 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 2263} Statements
11b60 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 of the form "DE
11b70 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e LETE FROM tablen
11b80 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 ame" with no.**
11b90 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 WHERE c
11ba0 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 lause shall not
11bb0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
11bc0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 returned.**
11bd0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 by [sqlite
11be0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
11bf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 )]..**.** ASSUMP
11c00 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 TIONS:.**.** {A1
11c10 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 2264} If a separ
11c20 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 ate thread makes
11c30 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 changes on the
11c40 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
11c50 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 nnection.**
11c60 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 while [sqli
11c70 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
11c80 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
11c90 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a then the value.*
11ca0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
11cb0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 ned is unpredict
11cc0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
11cd0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 ningful..*/.int
11ce0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
11cf0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
11d00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
11d10 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
11d20 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
11d30 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 {H12270} <S3050
11d40 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0>.**.** This fu
11d50 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e nction causes an
11d60 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 y pending databa
11d70 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 se operation to
11d80 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 abort and.** ret
11d90 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 urn at its earli
11da0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e est opportunity.
11db0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
11dc0 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 typically.** ca
11dd0 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 lled in response
11de0 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f to a user actio
11df0 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 n such as pressi
11e00 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f ng "Cancel".** o
11e10 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 r Ctrl-C where t
11e20 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 he user wants a
11e30 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 long query opera
11e40 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 tion to halt.**
11e50 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a immediately..**.
11e60 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f ** It is safe to
11e70 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
11e80 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 ne from a thread
11e90 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
11ea0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 the.** thread th
11eb0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 at is currently
11ec0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 running the data
11ed0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 base operation.
11ee0 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f But it.** is no
11ef0 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 t safe to call t
11f00 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
11f10 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
11f20 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a nection] that.**
11f30 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 is closed or mi
11f40 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 ght close before
11f50 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
11f60 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
11f70 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 .** If an SQL op
11f80 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 eration is very
11f90 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 nearly finished
11fa0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
11fb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 .** sqlite3_inte
11fc0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 rrupt() is calle
11fd0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 d, then it might
11fe0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 not have an opp
11ff0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 ortunity.** to b
12000 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e e interrupted an
12010 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 d might continue
12020 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
12030 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 **.** An SQL ope
12040 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 ration that is i
12050 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 nterrupted will
12060 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 return [SQLITE_I
12070 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 NTERRUPT]..** If
12080 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 the interrupted
12090 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
120a0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 s an INSERT, UPD
120b0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
120c0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 * that is inside
120d0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
120e0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 nsaction, then t
120f0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 he entire transa
12100 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 ction.** will be
12110 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
12120 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a omatically..**.*
12130 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
12140 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
12150 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e has no effect on
12160 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
12170 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
12180 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 ted after sqlite
12190 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
121a0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 turns..**.** INV
121b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
121c0 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c H12271} The [sql
121d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
121e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
121f0 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 force all runni
12200 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 ng.** S
12210 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 QL statements as
12220 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
12230 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
12240 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 connection.**
12250 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 to halt a
12260 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 fter processing
12270 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 at most one addi
12280 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 tional row of da
12290 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 ta..**.** {H1227
122a0 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 2} Any SQL state
122b0 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 ment that is int
122c0 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c errupted by [sql
122d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
122e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 ].** wi
122f0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
12300 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a E_INTERRUPT]..**
12310 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a .** ASSUMPTIONS:
12320 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 .**.** {A12279}
12330 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
12340 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
12350 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 s while [sqlite3
12360 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a _interrupt()].**
12370 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e is run
12380 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 ning then bad th
12390 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 ings will likely
123a0 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 happen..*/.void
123b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
123c0 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f pt(sqlite3*);../
123d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
123e0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
123f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 QL Statement Is
12400 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 Complete {H10510
12410 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S70200>.**.**
12420 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
12430 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 are useful for c
12440 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
12450 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
12460 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
12470 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
12480 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f seems to form co
12490 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 mplete a SQL sta
124a0 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
124b0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
124c0 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
124d0 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
124e0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
124f0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
12500 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
12510 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 eturn true if th
12520 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a e input string.*
12530 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 * appears to be
12540 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
12550 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 tatement. A sta
12560 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 tement is judged
12570 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 to be.** comple
12580 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 te if it ends wi
12590 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 th a semicolon t
125a0 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 oken and is not
125b0 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a a fragment of a.
125c0 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 ** CREATE TRIGGE
125d0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 R statement. Se
125e0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 micolons that ar
125f0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 e embedded withi
12600 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 n.** string lite
12610 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 rals or quoted i
12620 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 dentifier names
12630 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 or comments are
12640 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 not.** independe
12650 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 nt tokens (they
12660 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 are part of the
12670 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 token in which t
12680 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 hey are.** embed
12690 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f ded) and thus do
126a0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 not count as a
126b0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e statement termin
126c0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ator..**.** Thes
126d0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f e routines do no
126e0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 t parse the SQL
126f0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a statements thus.
12700 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 ** will not dete
12710 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 ct syntactically
12720 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a incorrect SQL..
12730 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
12740 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d :.**.** {H10511}
12750 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 A successful ev
12760 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c aluation of [sql
12770 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d ite3_complete()]
12780 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
12790 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
127a0 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 e16()] functions
127b0 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 shall.**
127c0 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 return a nume
127d0 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c ric 1 if and onl
127e0 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f y if the last no
127f0 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 n-whitespace.**
12800 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 token i
12810 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 n their input is
12820 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 a semicolon tha
12830 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 t is not in betw
12840 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 een.**
12850 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e the BEGIN and EN
12860 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 D of a CREATE TR
12870 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e IGGER statement.
12880 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 .**.** {H10512}
12890 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f If a memory allo
128a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 cation error occ
128b0 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e urs during an in
128c0 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 vocation.**
128d0 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 of [sqlite3
128e0 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 _complete()] or
128f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
12900 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a e16()] then the.
12910 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 ** rout
12920 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ine shall return
12930 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
12940 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f .**.** ASSUMPTIO
12950 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 NS:.**.** {A1051
12960 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 2} The input to
12970 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
12980 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
12990 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
129a0 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 * UTF-8
129b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
129c0 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 A10513} The inpu
129d0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
129e0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 mplete16()] must
129f0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
12a00 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 nated.**
12a10 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 UTF-16 string
12a20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
12a30 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c rder..*/.int sql
12a40 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
12a50 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
12a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
12a70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 lete16(const voi
12a80 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d *sql);../*.**
12a90 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 CAPI3REF: Regist
12aa0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f er A Callback To
12ab0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 Handle SQLITE_B
12ac0 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 USY Errors {H123
12ad0 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 10} <S40400>.**.
12ae0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
12af0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
12b00 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 function that mi
12b10 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
12b20 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
12b30 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
12b40 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 open a database
12b50 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 table that anot
12b60 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
12b70 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 process has loc
12b80 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ked..**.** If th
12b90 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
12ba0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 is NULL, then [S
12bb0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
12bc0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
12bd0 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 CKED].** is retu
12be0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 rned immediately
12bf0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 upon encounteri
12c00 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 ng the lock. If
12c10 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
12c20 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c k.** is not NULL
12c30 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 , then the callb
12c40 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f ack will be invo
12c50 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 ked with two arg
12c60 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 uments..**.** Th
12c70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
12c80 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 to the handler
12c90 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
12ca0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 void* pointer w
12cb0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 hich.** is the t
12cc0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
12cd0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
12ce0 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 ndler(). The se
12cf0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
12d00 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
12d10 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
12d20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
12d30 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
12d40 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
12d50 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 n invoked for th
12d60 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 is locking event
12d70 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 . If the.** bus
12d80 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
12d90 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
12da0 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
12db0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
12dc0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
12dd0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
12de0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
12df0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
12e00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
12e10 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b If the callback
12e20 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
12e30 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 o, then another
12e40 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 attempt.** is ma
12e50 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 de to open the d
12e60 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 atabase for read
12e70 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c ing and the cycl
12e80 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a e repeats..**.**
12e90 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 The presence of
12ea0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
12eb0 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 does not guarant
12ec0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 ee that it will
12ed0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 be invoked.** wh
12ee0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b en there is lock
12ef0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 contention. If
12f00 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
12f10 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 s that invoking
12f20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 the busy.** hand
12f30 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
12f40 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 in a deadlock,
12f50 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 it will go ahead
12f60 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
12f70 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 ITE_BUSY].** or
12f80 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
12f90 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f OCKED] instead o
12fa0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 f invoking the b
12fb0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 usy handler..**
12fc0 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 Consider a scena
12fd0 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 rio where one pr
12fe0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 ocess is holding
12ff0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 a read lock tha
13000 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e t.** it is tryin
13010 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 g to promote to
13020 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
13030 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 and.** a second
13040 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
13050 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f ng a reserved lo
13060 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 ck that it is tr
13070 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f ying.** to promo
13080 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 te to an exclusi
13090 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 ve lock. The fi
130a0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e rst process cann
130b0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 ot proceed.** be
130c0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
130d0 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e ked by the secon
130e0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 d and the second
130f0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a process cannot.
13100 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 ** proceed becau
13110 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
13120 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 by the first.
13130 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 If both processe
13140 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 s.** invoke the
13150 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e busy handlers, n
13160 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 either will make
13170 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 any progress.
13180 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 Therefore,.** SQ
13190 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 Lite returns [SQ
131a0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 LITE_BUSY] for t
131b0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
131c0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 , hoping that th
131d0 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 is.** will induc
131e0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 e the first proc
131f0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 ess to release i
13200 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 ts read lock and
13210 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 allow.** the se
13220 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 cond process to
13230 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 proceed..**.** T
13240 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
13250 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
13260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
13270 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 ITE_BUSY] error
13280 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 is converted to
13290 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
132a0 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 OCKED].** when S
132b0 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 QLite is in the
132c0 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 middle of a larg
132d0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 e transaction wh
132e0 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 ere all the.** c
132f0 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 hanges will not
13300 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d fit into the in-
13310 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 memory cache. S
13320 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c QLite will.** al
13330 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 ready hold a RES
13340 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 ERVED lock on th
13350 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c e database file,
13360 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a but it needs.**
13370 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 to promote this
13380 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 lock to EXCLUSI
13390 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 VE so that it ca
133a0 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a n spill cache.**
133b0 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 pages into the
133c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
133d0 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f thout harm to co
133e0 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 ncurrent.** read
133f0 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 ers. If it is u
13400 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 nable to promote
13410 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 the lock, then
13420 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a the in-memory.**
13430 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c cache will be l
13440 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 eft in an incons
13450 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 istent state and
13460 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a so the error.**
13470 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 code is promote
13480 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 d from the relat
13490 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 ively benign [SQ
134a0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a LITE_BUSY] to.**
134b0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 the more severe
134c0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
134d0 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 LOCKED]. This e
134e0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 rror code promot
134f0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e ion.** forces an
13500 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 automatic rollb
13510 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 ack of the chang
13520 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 es. See the.**
13530 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 <a href="/cvstra
13540 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 c/wiki?p=Corrupt
13550 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 ionFollowingBusy
13560 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 Error">.** Corru
13570 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
13580 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 syError</a> wiki
13590 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 page for a disc
135a0 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a ussion of why.**
135b0 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 this is importa
135c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 nt..**.** There
135d0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
135e0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
135f0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 r defined for ea
13600 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ch.** [database
13610 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 connection]. Se
13620 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 tting a new busy
13630 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 handler clears
13640 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c any.** previousl
13650 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 y set handler.
13660 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
13670 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
13680 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
13690 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
136a0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
136b0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
136c0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
136d0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
136e0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
136f0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
13700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13710 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
13720 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
13730 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
13740 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
13750 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
13760 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 ior..** .** INVA
13770 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
13780 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 12311} The [sqli
13790 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
137a0 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f (D,C,A)] functio
137b0 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a n shall replace.
137c0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79 ** busy
137d0 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 callback in the
137e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
137f0 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 ction] D with a
13800 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
13810 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
13820 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 er C and applica
13830 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
13840 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 r A..**.** {H123
13850 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 12} Newly create
13860 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e d [database conn
13870 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 ections] shall h
13880 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 ave a busy.**
13890 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f handler o
138a0 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 f NULL..**.** {H
138b0 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 12314} When two
138c0 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 or more [databas
138d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 e connections] s
138e0 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 hare a.**
138f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 [sqlite3_enab
13900 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 le_shared_cache
13910 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c | common cache],
13920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
13930 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f busy handler fo
13940 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 r the database c
13950 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e onnection curren
13960 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 tly using.**
13970 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20 the cache
13980 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 shall be invoked
13990 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 when the cache
139a0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 encounters a loc
139b0 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 k..**.** {H12316
139c0 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 } If a busy hand
139d0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ler callback ret
139e0 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 urns zero, then
139f0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 the SQLite inter
13a00 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 face.**
13a10 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 that provoked t
13a20 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 he locking event
13a30 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 shall return [S
13a40 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a QLITE_BUSY]..**.
13a50 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 ** {H12318} SQLi
13a60 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 te shall invokes
13a70 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
13a80 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d r with two argum
13a90 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 ents which.**
13aa0 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 are a cop
13ab0 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 y of the pointer
13ac0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 supplied by the
13ad0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
13ae0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
13af0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
13b00 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 ler()] and a cou
13b10 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 nt of the number
13b20 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 of prior.**
13b30 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e invocation
13b40 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 s of the busy ha
13b50 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 ndler for the sa
13b60 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 me locking event
13b70 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 ..**.** ASSUMPTI
13b80 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 ONS:.**.** {A123
13b90 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 19} A busy handl
13ba0 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 er must not clos
13bb0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
13bc0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 onnection.**
13bd0 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 or [prepar
13be0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
13bf0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
13c00 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a usy handler..*/.
13c10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
13c20 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
13c30 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
13c40 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
13c50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
13c60 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
13c70 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 t {H12340} <S404
13c80 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 10>.**.** This r
13c90 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 outine sets a [s
13ca0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
13cb0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c ler | busy handl
13cc0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a er] that sleeps.
13cd0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 ** for a specifi
13ce0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d ed amount of tim
13cf0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 e when a table i
13d00 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 s locked. The h
13d10 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
13d20 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
13d30 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
13d40 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
13d50 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
13d60 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
13d70 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 ated. {H12343} A
13d80 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 fter "ms" millis
13d90 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
13da0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
13db0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
13dc0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
13dd0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
13de0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
13df0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
13e00 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
13e10 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 .**.** Calling t
13e20 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
13e30 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
13e40 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
13e50 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
13e60 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
13e70 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ndlers..**.** Th
13e80 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
13e90 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
13ea0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
13eb0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
13ec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
13ed0 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
13ee0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
13ef0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
13f00 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
13f10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
13f20 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
13f30 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
13f40 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
13f50 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
13f60 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
13f70 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ared..**.** INVA
13f80 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
13f90 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 12341} The [sqli
13fa0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
13fb0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 ()] function sha
13fc0 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 ll override any
13fd0 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 prior.**
13fe0 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f [sqlite3_busy_
13ff0 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 timeout()] or [s
14000 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
14010 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a ler()] setting.*
14020 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 * on th
14030 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
14040 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
14050 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 .** {H12343} If
14060 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
14070 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 r to [sqlite3_bu
14080 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 sy_timeout()] is
14090 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 less than.**
140a0 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 or equal
140b0 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 to zero, then th
140c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 e busy handler s
140d0 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 hall be cleared
140e0 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 so that.**
140f0 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 all subseque
14100 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 nt locking event
14110 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 s immediately re
14120 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
14130 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 Y]..**.** {H1234
14140 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 4} If the 2nd pa
14150 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
14160 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
14170 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 ()] is a positiv
14180 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 e.** nu
14190 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 mber N, then a b
141a0 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c usy handler shal
141b0 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65 l be set that re
141c0 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a peatedly calls.*
141d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78 * the x
141e0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 Sleep() method i
141f0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 n the [sqlite3_v
14200 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 fs | VFS interfa
14210 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 ce] until.**
14220 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65 either the
14230 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 lock clears or
14240 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 until the cumula
14250 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a tive sleep time.
14260 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f ** repo
14270 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c rted back by xSl
14280 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 eep() exceeds N
14290 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f milliseconds..*/
142a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
142b0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 y_timeout(sqlite
142c0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 3*, int ms);../*
142d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
142e0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e nvenience Routin
142f0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 es For Running Q
14300 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 ueries {H12370}
14310 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 <S10000>.**.** D
14320 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e efinition: A <b>
14330 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e result table</b>
14340 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 is memory data
14350 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 structure create
14360 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d by the.** [sql
14370 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
14380 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 ] interface. A
14390 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 result table rec
143a0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ords the.** comp
143b0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c lete query resul
143c0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d ts from one or m
143d0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a ore queries..**.
143e0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e ** The table con
143f0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 ceptually has a
14400 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 number of rows a
14410 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 nd columns. But
14420 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 .** these number
14430 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f s are not part o
14440 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
14450 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 le itself. Thes
14460 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 e.** numbers are
14470 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 obtained separa
14480 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 tely. Let N be
14490 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
144a0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 ws.** and M be t
144b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
144c0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 umns..**.** A re
144d0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e sult table is an
144e0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
144f0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 rs to zero-termi
14500 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
14510 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ngs..** There ar
14520 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e e (N+1)*M elemen
14530 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e ts in the array.
14540 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f The first M po
14550 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 inters point.**
14560 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
14570 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
14580 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d contain the nam
14590 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
145a0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e s..** The remain
145b0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 ing entries all
145c0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 point to query r
145d0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 esults. NULL va
145e0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 lues result.** i
145f0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e n NULL pointers.
14600 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 All other valu
14610 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 es are in their
14620 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
14630 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
14640 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 representation a
14650 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
14660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
14670 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 xt()]..**.** A r
14680 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 esult table migh
14690 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 t consist of one
146a0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 or more memory
146b0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 allocations..**
146c0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
146d0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 o pass a result
146e0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 table directly t
146f0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
14700 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 )]..** A result
14710 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 table should be
14720 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e deallocated usin
14730 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f g [sqlite3_free_
14740 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
14750 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 As an example of
14760 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
14770 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 e format, suppos
14780 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 e a query result
14790 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 .** is as follow
147a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
147b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
147c0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 Name
147d0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 | Age.**
147e0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------------
147f0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 --------.**
14800 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c Alice |
14810 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 43.** Bo
14820 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a b | 28.*
14830 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 * Cindy
14840 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 | 21.** </p
14850 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
14860 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 .**.** There are
14870 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d two column (M==
14880 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 2) and three row
14890 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 s (N==3). Thus
148a0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 the.** result ta
148b0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 ble has 8 entrie
148c0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 s. Suppose the
148d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
148e0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 stored.** in an
148f0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 array names azRe
14900 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 sult. Then azRe
14910 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 sult holds this
14920 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c content:.**.** <
14930 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
14940 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
14950 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 ult[0] = "Na
14960 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 me";.** a
14970 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d zResult[1] =
14980 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Age";.**
14990 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 azResult[2
149a0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 ] = "Alice";.**
149b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
149c0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a #91;3] = "43";.*
149d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
149e0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 t[4] = "Bob"
149f0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
14a00 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 sult[5] = "2
14a10 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 8";.** az
14a20 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 Result[6] =
14a30 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 "Cindy";.**
14a40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
14a50 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 7] = "21";.** </
14a60 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
14a70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
14a80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
14a90 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 function evaluat
14aa0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a es one or more.*
14ab0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 * semicolon-sepa
14ac0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d rated SQL statem
14ad0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f ents in the zero
14ae0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
14af0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 8.** string of i
14b00 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ts 2nd parameter
14b10 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 . It returns a
14b20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
14b30 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
14b40 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
14b50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
14b60 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 After the calli
14b70 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 ng function has
14b80 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
14b90 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 he result, it sh
14ba0 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 ould.** pass the
14bb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
14bc0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
14bd0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
14be0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f le() in order to
14bf0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 .** release the
14c00 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 memory that was
14c10 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 malloced. Becau
14c20 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 se of the way th
14c30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e.** [sqlite3_ma
14c40 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 lloc()] happens
14c50 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 within sqlite3_g
14c60 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 et_table(), the
14c70 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 calling.** funct
14c80 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 ion must not try
14c90 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 to call [sqlite
14ca0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 3_free()] direct
14cb0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 ly. Only.** [sq
14cc0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
14cd0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 ()] is able to r
14ce0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
14cf0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 y properly and s
14d00 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 afely..**.** The
14d10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
14d20 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 le() interface i
14d30 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 s implemented as
14d40 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e a wrapper aroun
14d50 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 d.** [sqlite3_ex
14d60 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 ec()]. The sqli
14d70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
14d80 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 routine does not
14d90 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 have access.**
14da0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 to any internal
14db0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
14dc0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 of SQLite. It u
14dd0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 ses only the pub
14de0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 lic.** interface
14df0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 defined here.
14e00 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 As a consequence
14e10 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 , errors that oc
14e20 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 cur in the.** wr
14e30 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 apper layer outs
14e40 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 ide of the inter
14e50 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 nal [sqlite3_exe
14e60 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f c()] call are no
14e70 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 t.** reflected i
14e80 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
14e90 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
14ea0 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 rrcode()] or [sq
14eb0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
14ec0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
14ed0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 S:.**.** {H12371
14ee0 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f } If a [sqlite3_
14ef0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 get_table()] fai
14f00 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ls a memory allo
14f10 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 cation, then.**
14f20 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c it shal
14f30 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c l free the resul
14f40 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f t table under co
14f50 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 nstruction, abor
14f60 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 t the.**
14f70 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 query in proce
14f80 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 ss, skip any sub
14f90 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c sequent queries,
14fa0 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 set the.**
14fb0 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 *pazResult
14fc0 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 output pointer t
14fd0 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 o NULL and retur
14fe0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
14ff0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d ..**.** {H12373}
15000 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e If the pnColumn
15010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
15020 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
15030 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a ()] is not NULL.
15040 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
15050 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e a successful in
15060 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
15070 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
15080 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 ] shall.**
15090 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 write the nu
150a0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
150b0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 in the.**
150c0 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 result set of
150d0 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 the query into
150e0 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a *pnColumn..**.**
150f0 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 {H12374} If the
15100 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 pnRow parameter
15110 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 to [sqlite3_get
15120 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 _table()] is not
15130 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 NULL.**
15140 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 then a success
15150 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ful invocation o
15160 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 f [sqlite3_get_t
15170 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a able()] shall.**
15180 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73 writes
15190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
151a0 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 ows in the.**
151b0 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 result se
151c0 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 t of the query i
151d0 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a nto *pnRow..**.*
151e0 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 * {H12376} A suc
151f0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
15200 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 on of [sqlite3_g
15210 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 et_table()] that
15220 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 computes.**
15230 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 N rows of
15240 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f result with C co
15250 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 lumns per row sh
15260 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 all make *pazRes
15270 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ult.**
15280 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 point to an arra
15290 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
152a0 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 (N+1)*C strings
152b0 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 where the first
152c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 .** C s
152d0 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d trings are colum
152e0 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 n names as obtai
152f0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 ned from.**
15300 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f [sqlite3_co
15310 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 lumn_name()] and
15320 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f the rest are co
15330 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 lumn result valu
15340 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f es.** o
15350 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
15360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
15370 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 t()]..**.** {H12
15380 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 379} The values
15390 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 in the pazResult
153a0 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 array returned
153b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f by [sqlite3_get_
153c0 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 table()].**
153d0 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 shall remai
153e0 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c n valid until cl
153f0 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eared by [sqlite
15400 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 3_free_table()].
15410 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 .**.** {H12382}
15420 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
15430 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c curs during eval
15440 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 uation of [sqlit
15450 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a e3_get_table()].
15460 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
15470 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 function shall s
15480 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f et *pazResult to
15490 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 NULL, write an
154a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a error message.**
154b0 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d into m
154c0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
154d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
154e0 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 loc()], make.**
154f0 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 **pzErr
15500 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 msg point to tha
15510 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c t error message,
15520 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a and return a.**
15530 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 approp
15540 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
15550 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 e]..*/.int sqlit
15560 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 e3_get_table(.
15570 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
15580 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
15590 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
155a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
155b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
155c0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
155d0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 char ***pazResu
155e0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 lt, /* Result
155f0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a s of the query *
15600 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 /. int *pnRow,
15610 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
15620 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f ber of result ro
15630 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ws written here
15640 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 */. int *pnColu
15650 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 mn, /* Nu
15660 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 mber of result c
15670 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 olumns written h
15680 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ere */. char **
15690 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f pzErrmsg /
156a0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
156b0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 ten here */.);.v
156c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
156d0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 _table(char **re
156e0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 sult);../*.** CA
156f0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 PI3REF: Formatte
15700 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e d String Printin
15710 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 g Functions {H17
15720 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 400} <S70000><S2
15730 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0000>.**.** Thes
15740 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
15750 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 orkalikes of the
15760 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
15770 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
15780 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
15790 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
157a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
157b0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
157c0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
157d0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
157e0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
157f0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
15800 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
15810 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
15820 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
15830 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
15840 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
15850 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
15860 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
15870 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 _free()]. Both
15880 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
15890 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
158a0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
158b0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
158c0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
158d0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
158e0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
158f0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
15900 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e ** In sqlite3_sn
15910 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
15920 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
15930 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
15940 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
15950 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
15960 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
15970 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
15980 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
15990 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
159a0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
159b0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
159c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
159d0 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 eter. Note that
159e0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 the order of the
159f0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 .** first two pa
15a00 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 rameters is reve
15a10 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e rsed from snprin
15a20 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 tf(). This is a
15a30 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 n.** historical
15a40 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 accident that ca
15a50 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 nnot be fixed wi
15a60 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a thout breaking.*
15a70 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
15a80 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 atibility. Note
15a90 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
15aa0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
15ab0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
15ac0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
15ad0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
15ae0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
15af0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
15b00 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
15b10 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 e buffer. We ad
15b20 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
15b30 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
15b40 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
15b50 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
15b60 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
15b70 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
15b80 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
15b90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
15ba0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
15bb0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
15bc0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
15bd0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 ibility..**.** A
15be0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
15bf0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
15c00 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
15c10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
15c20 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
15c30 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
15c40 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
15c50 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 terminated. The
15c60 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
15c70 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
15c80 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
15c90 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
15ca0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
15cb0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
15cc0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
15cd0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
15ce0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
15cf0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
15d00 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
15d10 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ters..**.** Thes
15d20 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 e routines all i
15d30 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 mplement some ad
15d40 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 ditional formatt
15d50 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 ing.** options t
15d60 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 hat are useful f
15d70 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 or constructing
15d80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
15d90 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 ** All of the us
15da0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 ual printf() for
15db0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
15dc0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 apply. In addit
15dd0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 ion, there.** is
15de0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c are "%q", "%Q",
15df0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
15e00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 s..**.** The %q
15e10 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
15e20 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
15e30 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
15e40 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ll-terminated.**
15e50 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
15e60 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
15e70 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
15e80 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
15e90 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
15ea0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
15eb0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
15ec0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 ring literal. B
15ed0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 y doubling each
15ee0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 '\''.** characte
15ef0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 r it escapes tha
15f00 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 t character and
15f10 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 allows it to be
15f20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a inserted into.**
15f30 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a the string..**.
15f40 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** For example,
15f50 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e assume the strin
15f60 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 g variable zText
15f70 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 contains text a
15f80 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
15f90 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
15fa0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 e>.** char *zTe
15fb0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 xt = "It's a hap
15fc0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 py day!";.** </p
15fd0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
15fe0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 .**.** One can u
15ff0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 se this text in
16000 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
16010 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
16020 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
16030 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
16040 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
16050 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
16060 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
16070 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a '%q')", zText);.
16080 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
16090 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
160a0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
160b0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
160c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
160d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 te>.**.** Becaus
160e0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 e the %q format
160f0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 string is used,
16100 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 the '\'' charact
16110 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 er in zText.** i
16120 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 s escaped and th
16130 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 e SQL generated
16140 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
16150 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
16160 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
16170 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
16180 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 LUES('It''s a ha
16190 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f ppy day!').** </
161a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
161b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 >.**.** This is
161c0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 correct. Had we
161d0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 used %s instead
161e0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 of %q, the gene
161f0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 rated SQL.** wou
16200 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c ld have looked l
16210 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
16220 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
16230 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
16240 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
16250 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 'It's a happy da
16260 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c y!');.** </pre><
16270 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
16280 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 ** This second e
16290 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c xample is an SQL
162a0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 syntax error.
162b0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c As a general rul
162c0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 e you should.**
162d0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e always use %q in
162e0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e stead of %s when
162f0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 inserting text
16300 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 into a string li
16310 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 teral..**.** The
16320 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
16330 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
16340 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
16350 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
16360 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
16370 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
16380 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
16390 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
163a0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
163b0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
163c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
163d0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
163e0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
163f0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
16400 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c le quotes) in pl
16410 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 ace of the %Q op
16420 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 tion. So, for e
16430 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
16440 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
16450 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
16460 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
16470 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
16480 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
16490 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
164a0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
164b0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
164c0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
164d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
164e0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
164f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
16500 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
16510 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
16520 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
16530 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
16540 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
16550 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
16560 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
16570 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
16580 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 The "%z" format
16590 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
165a0 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 s exactly like "
165b0 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 %s" with the.**
165c0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
165d0 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
165e0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
165f0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
16600 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
16610 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
16620 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
16630 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 put string. {END
16640 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e }.**.** INVARIAN
16650 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 TS:.**.** {H1740
16660 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 3} The [sqlite3
16670 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 _mprintf()] and
16680 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 [sqlite3_vmprint
16690 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a f()] interfaces.
166a0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 ** ret
166b0 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 urn either point
166c0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d ers to zero-term
166d0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
166e0 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 ings held in.**
166f0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 memory
16700 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
16710 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
16720 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ] or NULL pointe
16730 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 rs if.**
16740 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 a call to [sq
16750 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
16760 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 fails..**.** {H1
16770 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 7406} The [sqli
16780 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
16790 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 interface writes
167a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
167b0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ed.**
167c0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 UTF-8 string int
167d0 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 o the buffer poi
167e0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 nted to by the s
167f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a econd parameter.
16800 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f ** pro
16810 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 vided that the f
16820 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
16830 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a s greater than z
16840 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 ero..**.** {H174
16850 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 07} The [sqlite
16860 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 3_snprintf()] in
16870 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
16880 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a write slots of.
16890 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 ** its
168a0 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 output buffer (
168b0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
168c0 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 eter) outside th
168d0 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 e range.**
168e0 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 of 0 throug
168f0 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 h N-1 (where N i
16900 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
16910 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 meter).**
16920 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f regardless o
16930 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 f the length of
16940 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 the string.**
16950 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 requeste
16960 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 d by the format
16970 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a specification..*
16980 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f /.char *sqlite3_
16990 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
169a0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a ar*,...);.char *
169b0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
169c0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
169d0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 _list);.char *sq
169e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 lite3_snprintf(i
169f0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
16a00 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a har*, ...);../*.
16a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
16a20 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 ory Allocation S
16a30 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 ubsystem {H17300
16a40 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a } <S20000>.**.**
16a50 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
16a60 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 uses these thr
16a70 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 ee routines for
16a80 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a all of its own.*
16a90 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 * internal memor
16aa0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
16ab0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 ds. "Core" in th
16ac0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 e previous sente
16ad0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 nce.** does not
16ae0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e include operatin
16af0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 g-system specifi
16b00 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 c VFS implementa
16b10 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 tion. The.** Wi
16b20 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e ndows VFS uses n
16b30 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 ative malloc() a
16b40 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f nd free() for so
16b50 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a me operations..*
16b60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
16b70 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e _malloc() routin
16b80 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
16b90 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a ter to a block.*
16ba0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c * of memory at l
16bb0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
16bc0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 length, where N
16bd0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 is the parameter
16be0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f ..** If sqlite3_
16bf0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 malloc() is unab
16c00 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 le to obtain suf
16c10 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 ficient free.**
16c20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 memory, it retur
16c30 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
16c40 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d r. If the param
16c50 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c eter N to.** sql
16c60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
16c70 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 zero or negativ
16c80 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d e then sqlite3_m
16c90 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a alloc() returns.
16ca0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
16cb0 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 r..**.** Calling
16cc0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
16cd0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 with a pointer p
16ce0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
16cf0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
16d00 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
16d10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
16d20 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d eleases that mem
16d30 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 ory so.** that i
16d40 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 t might be reuse
16d50 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f d. The sqlite3_
16d60 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 free() routine i
16d70 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 s.** a no-op if
16d80 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
16d90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
16da0 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 Passing a NULL p
16db0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c ointer.** to sql
16dc0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 ite3_free() is h
16dd0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 armless. After
16de0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d being freed, mem
16df0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 ory.** should ne
16e00 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f ither be read no
16e10 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e r written. Even
16e20 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 reading previou
16e30 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d sly freed.** mem
16e40 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 ory might result
16e50 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 in a segmentati
16e60 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 on fault or othe
16e70 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a r severe error..
16e80 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 ** Memory corrup
16e90 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 tion, a segmenta
16ea0 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f tion fault, or o
16eb0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
16ec0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c r.** might resul
16ed0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 t if sqlite3_fre
16ee0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 e() is called wi
16ef0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f th a non-NULL po
16f00 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 inter that.** wa
16f10 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 s not obtained f
16f20 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
16f30 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
16f40 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a realloc()..**.**
16f50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 The sqlite3_rea
16f60 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 lloc() interface
16f70 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 attempts to res
16f80 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d ize a.** prior m
16f90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
16fa0 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 to be at least
16fb0 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e N bytes, where N
16fc0 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e is the.** secon
16fd0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 d parameter. Th
16fe0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
16ff0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 ion to be resize
17000 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a d is the first.*
17010 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 * parameter. If
17020 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
17030 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
17040 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 realloc().** is
17050 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
17060 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
17070 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
17080 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
17090 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 te3_malloc(N) wh
170a0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
170b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
170c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
170d0 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 ()..** If the se
170e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
170f0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
17100 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a c() is zero or.*
17110 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 * negative then
17120 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
17130 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 exactly the same
17140 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 as calling.** s
17150 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 qlite3_free(P) w
17160 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 here P is the fi
17170 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
17180 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
17190 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 ()..** sqlite3_r
171a0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 ealloc() returns
171b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
171c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
171d0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 n.** of at least
171e0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
171f0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 or NULL if suff
17200 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 icient memory is
17210 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
17220 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a If M is the siz
17230 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 e of the prior a
17240 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 llocation, then
17250 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a min(N,M) bytes.*
17260 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 * of the prior a
17270 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f llocation are co
17280 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 pied into the be
17290 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 ginning of buffe
172a0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 r returned.** by
172b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
172c0 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 () and the prior
172d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 allocation is f
172e0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 reed..** If sqli
172f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
17300 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e turns NULL, then
17310 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
17320 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 ation.** is not
17330 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 freed..**.** The
17340 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 memory returned
17350 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
17360 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 oc() and sqlite3
17370 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 _realloc().** is
17380 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 always aligned
17390 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 to at least an 8
173a0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 byte boundary.
173b0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 {END}.**.** The
173c0 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e default implemen
173d0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 tation of the me
173e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
173f0 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a subsystem uses.*
17400 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 * the malloc(),
17410 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 realloc() and fr
17420 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 ee() provided by
17430 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
17440 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 library..** {H17
17450 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 382} However, if
17460 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
17470 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
17480 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 SQLITE_MEMORY_SI
17490 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 ZE=<i>NNN</i> C
174a0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
174b0 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e ro (where <i>NNN
174c0 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e </i>.** is an in
174d0 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c teger), then SQL
174e0 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61 ite create a sta
174f0 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 tic array of at
17500 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c least.** <i>NNN<
17510 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a /i> bytes in siz
17520 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 e and uses that
17530 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 array for all of
17540 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 its dynamic.**
17550 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
17560 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 n needs. {END}
17570 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 Additional memor
17580 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 y allocator opti
17590 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 ons.** may be ad
175a0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
175b0 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e leases..**.** In
175c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
175d0 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 3.5.0 and 3.5.1,
175e0 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 it was possible
175f0 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 to define.** th
17600 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 e SQLITE_OMIT_ME
17610 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 MORY_ALLOCATION
17620 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 which would caus
17630 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a e the built-in.*
17640 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
17650 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
17660 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 es to be omitted
17670 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 . That capabili
17680 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 ty.** is no long
17690 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e er provided. On
176a0 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f ly built-in memo
176b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 ry allocators ca
176c0 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a n be used..**.**
176d0 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 The Windows OS
176e0 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 interface layer
176f0 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 calls.** the sys
17700 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 tem malloc() and
17710 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 free() directly
17720 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 when converting
17730 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 .** filenames be
17740 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 tween the UTF-8
17750 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 encoding used by
17760 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 SQLite.** and w
17770 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 hatever filename
17780 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 encoding is use
17790 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 d by the particu
177a0 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 lar Windows.** i
177b0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 nstallation. Me
177c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
177d0 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 errors are detec
177e0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
177f0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 are reported ba
17800 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
17810 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
17820 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
17830 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
17840 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 _NOMEM]..**.** I
17850 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
17860 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b {H17303} The [
17870 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
17880 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
17890 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f urns either a po
178a0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 inter to.**
178b0 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 a newly ch
178c0 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 ecked-out block
178d0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
178e0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a tes of memory.**
178f0 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 that
17900 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 is 8-byte aligne
17910 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 d, or it returns
17920 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 NULL if it is u
17930 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 nable.**
17940 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 to fulfill th
17950 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a e request..**.**
17960 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b {H17304} The [
17970 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
17980 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
17990 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
179a0 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 ter if.**
179b0 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 N is less th
179c0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
179d0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 ero..**.** {H173
179e0 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 05} The [sqlite
179f0 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 3_free(P)] inter
17a00 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 face releases me
17a10 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a mory previously.
17a20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 ** ret
17a30 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
17a40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 te3_malloc()] or
17a50 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
17a60 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 c()],.**
17a70 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 making it ava
17a80 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 ilable for reuse
17a90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d ..**.** {H17306}
17aa0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c A call to [sql
17ab0 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d ite3_free(NULL)]
17ac0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
17ad0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 o-op..**.** {H17
17ae0 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 310} A call to
17af0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
17b00 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 (0,N)] is equiva
17b10 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a lent to a call.*
17b20 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b * to [
17b30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
17b40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 )]..**.** {H1731
17b50 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 2} A call to [s
17b60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 qlite3_realloc(P
17b70 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 ,0)] is equivale
17b80 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 nt to a call.**
17b90 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 to [sq
17ba0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a lite3_free(P)]..
17bb0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 **.** {H17315}
17bc0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
17bd0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 uses [sqlite3_ma
17be0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
17bf0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 3_realloc()],.**
17c00 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b and [
17c10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
17c20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d for all of its m
17c30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
17c40 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
17c50 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e deallocation n
17c60 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 eeds..**.** {H17
17c70 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 318} The [sqlit
17c80 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d e3_realloc(P,N)]
17c90 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
17ca0 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e ns either a poin
17cb0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ter.**
17cc0 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 to a block of c
17cd0 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 hecked-out memor
17ce0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 y of at least N
17cf0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a bytes in size.**
17d00 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 that
17d10 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 is 8-byte aligne
17d20 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 d, or a NULL poi
17d30 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 nter..**.** {H17
17d40 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 321} When [sqli
17d50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 te3_realloc(P,N)
17d60 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d ] returns a non-
17d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 NULL pointer, it
17d80 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 first.**
17d90 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 copies the f
17da0 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 irst K bytes of
17db0 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 content from P i
17dc0 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a nto the newly.**
17dd0 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 alloc
17de0 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 ated block, wher
17df0 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 e K is the lesse
17e00 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 r of N and the s
17e10 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 ize of.**
17e20 20 20 20 20 74 68 65 20 62 75 66 66 65 72 20 50 the buffer P
17e30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d ..**.** {H17322}
17e40 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f When [sqlite3_
17e50 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 realloc(P,N)] re
17e60 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c turns a non-NULL
17e70 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 pointer, it fir
17e80 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 st.**
17e90 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 releases the buf
17ea0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 fer P..**.** {H1
17eb0 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 7323} When [sql
17ec0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e ite3_realloc(P,N
17ed0 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c )] returns NULL,
17ee0 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73 the buffer P is
17ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f .** no
17f00 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 t modified or re
17f10 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 leased..**.** AS
17f20 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a SUMPTIONS:.**.**
17f30 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 {A17350} The p
17f40 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 ointer arguments
17f50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
17f60 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
17f70 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
17f80 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 must b
17f90 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 e either NULL or
17fa0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f else pointers o
17fb0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 btained from a p
17fc0 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 rior.**
17fd0 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 invocation of
17fe0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
17ff0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
18000 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
18010 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ave.**
18020 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
18030 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 leased..**.** {A
18040 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 17351} The appl
18050 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
18060 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 read or write a
18070 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 ny part of.**
18080 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 a block
18090 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 of memory after
180a0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 it has been rele
180b0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 ased using.**
180c0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
180d0 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c _free()] or [sql
180e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e ite3_realloc()].
180f0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
18100 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 3_malloc(int);.v
18110 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
18120 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 lloc(void*, int)
18130 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
18140 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a ree(void*);../*.
18150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
18160 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 ory Allocator St
18170 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 atistics {H17370
18180 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a } <S30210>.**.**
18190 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
181a0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
181b0 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
181c0 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
181d0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
181e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
181f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
18200 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
18210 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
18220 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
18230 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
18240 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
18250 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
18260 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
18270 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 .** {H17371} The
18280 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
18290 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 _used()] routine
182a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
182b0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 ber of bytes.**
182c0 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f of memo
182d0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
182e0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
182f0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
18300 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 )..**.** {H17373
18310 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d } The [sqlite3_m
18320 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
18330 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
18340 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a ns the maximum.*
18350 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
18360 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d of [sqlite3_mem
18370 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 ory_used()] sinc
18380 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 e the high-water
18390 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 mark.**
183a0 20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 was last reset
183b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d ..**.** {H17374}
183c0 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 The values retu
183d0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
183e0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
183f0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
18400 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
18410 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 highwater()] inc
18420 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 lude any overhea
18430 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 d.** ad
18440 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
18450 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
18460 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
18470 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 malloc()],.**
18480 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f but not o
18490 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 verhead added by
184a0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 the any underly
184b0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 ing system libra
184c0 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 ry.** r
184d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 outines that [sq
184e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
184f0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 may call..**.**
18500 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d {H17375} The mem
18510 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d ory high-water m
18520 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 ark is reset to
18530 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
18540 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 e of.**
18550 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
18560 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 _used()] if and
18570 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 only if the para
18580 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 meter to.**
18590 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 [sqlite3_me
185a0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
185b0 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 ] is true. The
185c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a value returned.*
185d0 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 * by [s
185e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
185f0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
18600 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
18610 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 rk.** p
18620 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 rior to the rese
18630 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e t..*/.sqlite3_in
18640 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
18650 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 ry_used(void);.s
18660 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
18670 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
18680 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 water(int resetF
18690 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 lag);../*.** CAP
186a0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 I3REF: Pseudo-Ra
186b0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 ndom Number Gene
186c0 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c rator {H17390} <
186d0 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S20000>.**.** SQ
186e0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 Lite contains a
186f0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
18700 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 udo-random numbe
18710 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e r generator (PRN
18720 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 G) used to.** se
18730 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 lect random ROWI
18740 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e Ds when insertin
18750 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e g new records in
18760 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a to a table that.
18770 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 ** already uses
18780 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 the largest poss
18790 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65 ible ROWID. The
187a0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 PRNG is also us
187b0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 ed for.** the bu
187c0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 ild-in random()
187d0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 and randomblob()
187e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 SQL functions.
187f0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
18800 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 allows.** applic
18810 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 ations to access
18820 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 the same PRNG f
18830 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 or other purpose
18840 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 s..**.** A call
18850 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 to this routine
18860 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f stores N bytes o
18870 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 f randomness int
18880 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a o buffer P..**.*
18890 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 * The first time
188a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
188b0 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 invoked (either
188c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 internally or b
188d0 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 y.** the applica
188e0 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 tion) the PRNG i
188f0 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 s seeded using r
18900 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
18910 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 ed.** from the x
18920 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f Randomness metho
18930 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 d of the default
18940 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
18950 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c bject..** On all
18960 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f subsequent invo
18970 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 cations, the pse
18980 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
18990 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
189a0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
189b0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
189c0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
189d0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
189e0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a ** method..**.**
189f0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
18a00 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54 68 65 20 ** {H17392} The
18a10 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e [sqlite3_randomn
18a20 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 ess(N,P)] interf
18a30 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79 74 ace writes N byt
18a40 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 es of.**
18a50 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 high-quality p
18a60 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 seudo-randomness
18a70 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a into buffer P..
18a80 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
18a90 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e randomness(int N
18aa0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a , void *P);../*.
18ab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
18ac0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 pile-Time Author
18ad0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ization Callback
18ae0 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31 s {H12500} <S701
18af0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
18b00 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 outine registers
18b10 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 a authorizer ca
18b20 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 llback with a pa
18b30 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
18b40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18b50 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 ], supplied in t
18b60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
18b70 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 t..** The author
18b80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
18b90 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 invoked as SQL
18ba0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 statements are b
18bb0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a eing compiled.**
18bc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 by [sqlite3_pre
18bd0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 pare()] or its v
18be0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 ariants [sqlite3
18bf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a _prepare_v2()],.
18c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
18c10 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 are16()] and [sq
18c20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
18c30 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f v2()]. At vario
18c40 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 us.** points dur
18c50 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 ing the compilat
18c60 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 ion process, as
18c70 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 logic is being c
18c80 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 reated.** to per
18c90 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 form various act
18ca0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 ions, the author
18cb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
18cc0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 invoked to.** s
18cd0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 ee if those acti
18ce0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ons are allowed.
18cf0 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 The authorizer
18d00 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
18d10 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
18d20 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 TE_OK] to allow
18d30 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c the action, [SQL
18d40 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 ITE_IGNORE] to d
18d50 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 isallow the.** s
18d60 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 pecific action b
18d70 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c ut allow the SQL
18d80 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f statement to co
18d90 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 ntinue to be.**
18da0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 compiled, or [SQ
18db0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 LITE_DENY] to ca
18dc0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 use the entire S
18dd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
18de0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 be.** rejected w
18df0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 ith an error. I
18e00 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 f the authorizer
18e10 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
18e20 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f s.** any value o
18e30 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
18e40 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 E_IGNORE], [SQLI
18e50 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 TE_OK], or [SQLI
18e60 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e TE_DENY].** then
18e70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
18e80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
18e90 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
18ea0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a hat triggered.**
18eb0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
18ec0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
18ed0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
18ee0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
18ef0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
18f00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
18f10 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 at means the ope
18f20 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 ration.** reques
18f30 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e ted is ok. When
18f40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
18f50 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 turns [SQLITE_DE
18f60 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c NY], the.** [sql
18f70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
18f80 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
18f90 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
18fa0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 ered the.** auth
18fb0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
18fc0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
18fd0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e essage explainin
18fe0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 g that.** access
18ff0 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 is denied. If
19000 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
19010 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 ode is [SQLITE_R
19020 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 EAD].** and the
19030 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
19040 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
19050 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 then the.** [pr
19060 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
19070 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 ] statement is c
19080 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 onstructed to su
19090 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 bstitute.** a NU
190a0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 LL value in plac
190b0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
190c0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 olumn that would
190d0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 have.** been re
190e0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b ad if [SQLITE_OK
190f0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 ] had been retur
19100 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ned. The [SQLIT
19110 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 E_IGNORE].** ret
19120 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 urn can be used
19130 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 to deny an untru
19140 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 sted user access
19150 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a to individual.*
19160 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 * columns of a t
19170 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 able..**.** The
19180 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
19190 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
191a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 r callback is a
191b0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 copy of the thir
191c0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
191d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 o the sqlite3_se
191e0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 t_authorizer() i
191f0 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 nterface. The se
19200 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a cond parameter.*
19210 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
19220 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 k is an integer
19230 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 [SQLITE_COPY | a
19240 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 ction code] that
19250 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 specifies.** th
19260 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 e particular act
19270 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
19280 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 ized. The third
19290 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 through sixth pa
192a0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 rameters.** to t
192b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 he callback are
192c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
192d0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e strings that con
192e0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a tain additional.
192f0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 ** details about
19300 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 the action to b
19310 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a e authorized..**
19320 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 .** An authorize
19330 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b r is used when [
19340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 sqlite3_prepare
19350 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 | preparing].**
19360 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 SQL statements f
19370 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 rom an untrusted
19380 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 source, to ensu
19390 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 re that the SQL
193a0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f statements.** do
193b0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 not try to acce
193c0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 ss data they are
193d0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 not allowed to
193e0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 see, or that the
193f0 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 y do not.** try
19400 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 to execute malic
19410 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 ious statements
19420 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 that damage the
19430 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a database. For.*
19440 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 * example, an ap
19450 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c plication may al
19460 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e low a user to en
19470 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a ter arbitrary.**
19480 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 SQL queries for
19490 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 evaluation by a
194a0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 database. But
194b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
194c0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
194d0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 the user to be
194e0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 able to make arb
194f0 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 itrary changes t
19500 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 o the.** databas
19510 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 e. An authorize
19520 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 r could then be
19530 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 put in place whi
19540 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 le the.** user-e
19550 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 ntered SQL is be
19560 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
19570 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d pare | prepared]
19580 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f that.** disallo
19590 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 ws everything ex
195a0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 cept [SELECT] st
195b0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
195c0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
195d0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 t need to proces
195e0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 s SQL from untru
195f0 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 sted sources.**
19600 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 might also consi
19610 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 der lowering res
19620 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 ource limits usi
19630 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ng [sqlite3_limi
19640 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 t()].** and limi
19650 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 ting database si
19660 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 ze using the [ma
19670 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
19680 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 RAGMA].** in add
19690 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 ition to using a
196a0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a n authorizer..**
196b0 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c .** Only a singl
196c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e e authorizer can
196d0 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 be in place on
196e0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
196f0 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 ction.** at a ti
19700 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 me. Each call t
19710 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
19720 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 thorizer overrid
19730 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f es the.** previo
19740 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c us call. Disabl
19750 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 e the authorizer
19760 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 by installing a
19770 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a NULL callback..
19780 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ** The authorize
19790 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 r is disabled by
197a0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 default..**.**
197b0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
197c0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 allback must not
197d0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
197e0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
197f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
19800 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
19810 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 voked the author
19820 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a izer callback..*
19830 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
19840 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
19850 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
19860 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
19870 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
19880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19890 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
198a0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
198b0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
198c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c .**.** When [sql
198d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
198e0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
198f0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
19900 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
19910 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 70 ent might be rep
19920 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
19930 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
19940 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
19950 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
19960 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
19970 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
19980 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
19990 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
199a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
199b0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
199c0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
199d0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f tep()]..**.** No
199e0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 te that the auth
199f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
19a00 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 is invoked only
19a10 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 during.** [sqlit
19a20 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
19a30 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 its variants.
19a40 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 Authorization is
19a50 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 not.** performe
19a60 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 d during stateme
19a70 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e nt evaluation in
19a80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
19a90 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
19aa0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 NTS:.**.** {H125
19ab0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 01} The [sqlite3
19ac0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
19ad0 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 D,...)] interfac
19ae0 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a e registers a.**
19af0 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 author
19b00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
19b10 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e th database conn
19b20 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 ection D..**.**
19b30 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 {H12502} The aut
19b40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
19b50 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 is invoked as S
19b60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
19b70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 e.** be
19b80 69 6e 67 20 70 61 72 73 65 65 64 20 61 6e 64 20 ing parseed and
19b90 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 compiled..**.**
19ba0 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 {H12503} If the
19bb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
19bc0 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ack returns any
19bd0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
19be0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
19bf0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 LITE_IGNORE], [S
19c00 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 QLITE_OK], or [S
19c10 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 QLITE_DENY], the
19c20 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
19c30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e e application in
19c40 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74 68 61 terface call tha
19c50 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 t caused.**
19c60 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72 69 the authori
19c70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 zer callback to
19c80 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 run shall fail w
19c90 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 ith an.**
19ca0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 [SQLITE_ERROR
19cb0 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 ] error code and
19cc0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
19cd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
19ce0 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 *.** {H12504} Wh
19cf0 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 en the authorize
19d00 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 r callback retur
19d10 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
19d20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
19d30 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72 69 descri
19d40 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 65 64 bed is processed
19d50 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a normally..**.**
19d60 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20 74 {H12505} When t
19d70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
19d80 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
19d90 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 SQLITE_DENY], th
19da0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 e.** ap
19db0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 plication interf
19dc0 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 ace call that ca
19dd0 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 used the.**
19de0 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 authorizer
19df0 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 callback to run
19e00 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 shall fail.**
19e10 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b with an [
19e20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 SQLITE_ERROR] er
19e30 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 ror code and an
19e40 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a error message.**
19e50 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61 69 explai
19e60 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73 73 ning that access
19e70 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a is denied..**.*
19e80 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68 * {H12506} If th
19e90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 e authorizer cod
19ea0 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d e (the 2nd param
19eb0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
19ec0 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 orizer.**
19ed0 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 callback) is
19ee0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e [SQLITE_READ] an
19ef0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
19f00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
19f10 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 s.** [S
19f20 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 QLITE_IGNORE], t
19f30 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 hen the prepared
19f40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
19f50 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 nstructed to.**
19f60 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20 insert
19f70 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 a NULL value in
19f80 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 place of the tab
19f90 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 le column that w
19fa0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20 ould have.**
19fb0 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 20 been read
19fc0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 if [SQLITE_OK] h
19fd0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 ad been returned
19fe0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d ..**.** {H12507}
19ff0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a If the authoriz
1a000 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 er code (the 2nd
1a010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1a020 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 e authorizer.**
1a030 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 callbac
1a040 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f k) is anything o
1a050 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1a060 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a E_READ], then.**
1a070 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75 a retu
1a080 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47 rn of [SQLITE_IG
1a090 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61 NORE] has the sa
1a0a0 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51 me effect as [SQ
1a0b0 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a LITE_DENY]..**.*
1a0c0 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66 * {H12510} The f
1a0d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1a0e0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
1a0f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
1a100 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 opy of.**
1a110 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61 72 the third par
1a120 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
1a130 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1a140 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 rizer()] interfa
1a150 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 ce..**.** {H1251
1a160 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 1} The second pa
1a170 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
1a180 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
1a190 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 teger.**
1a1a0 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c [SQLITE_COPY |
1a1b0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 action code] th
1a1c0 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 at specifies the
1a1d0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 particular acti
1a1e0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 on.** t
1a1f0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
1a200 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20 .**.** {H12512}
1a210 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
1a220 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
1a230 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 rs to the callba
1a240 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 ck are.**
1a250 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 zero-terminat
1a260 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
1a270 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 contain.**
1a280 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 additional d
1a290 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
1a2a0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
1a2b0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
1a2c0 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 {H12520} Each ca
1a2d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
1a2e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
1a2f0 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20 overrides.**
1a300 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 69 any previ
1a310 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 ously installed
1a320 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a authorizer..**.*
1a330 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c * {H12521} A NUL
1a340 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 L authorizer mea
1a350 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f ns that no autho
1a360 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 rization.**
1a370 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 callback is
1a380 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
1a390 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 {H12522} The def
1a3a0 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 ault authorizer
1a3b0 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 is NULL..*/.int
1a3c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1a3d0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 orizer(. sqlite
1a3e0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 3*,. int (*xAut
1a3f0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e h)(void*,int,con
1a400 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
1a410 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1a420 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 ,const char*),.
1a430 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 void *pUserData
1a440 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
1a450 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
1a460 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 Return Codes {H1
1a470 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2590} <H12500>.*
1a480 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
1a490 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1a4a0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 | authorizer ca
1a4b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d llback function]
1a4c0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 must.** return
1a4d0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f either [SQLITE_O
1a4e0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 K] or one of the
1a4f0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 se two constants
1a500 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 in order.** to
1a510 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 signal SQLite wh
1a520 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
1a530 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 action is permi
1a540 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a tted. See the.*
1a550 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 * [sqlite3_set_a
1a560 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
1a570 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 orizer documenta
1a580 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 tion] for additi
1a590 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
1a5a0 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ion..*/.#define
1a5b0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 SQLITE_DENY 1
1a5c0 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 /* Abort the S
1a5d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 QL statement wit
1a5e0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 h an error */.#d
1a5f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e efine SQLITE_IGN
1a600 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 ORE 2 /* Don't
1a610 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 allow access, b
1a620 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 ut don't generat
1a630 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f e an error */../
1a640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
1a650 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e uthorizer Action
1a660 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 Codes {H12550}
1a670 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H12500>.**.** T
1a680 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
1a690 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e authorizer()] in
1a6a0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
1a6b0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
1a6c0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 ction.** that is
1a6d0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 invoked to auth
1a6e0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 orize certain SQ
1a6f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 L statement acti
1a700 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ons. The.** sec
1a710 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
1a720 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
1a730 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 an integer code
1a740 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
1a750 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 ** what action i
1a760 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a s being authoriz
1a770 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 ed. These are t
1a780 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f he integer actio
1a790 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 n codes that.**
1a7a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1a7b0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 allback may be p
1a7c0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 assed..**.** The
1a7d0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 se action code v
1a7e0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 alues signify wh
1a7f0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 at kind of opera
1a800 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a tion is to be.**
1a810 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
1a820 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 e 3rd and 4th pa
1a830 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 rameters to the
1a840 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a authorization.**
1a850 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1a860 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d on will be param
1a870 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 eters or NULL de
1a880 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 pending on which
1a890 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 of these.** cod
1a8a0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 es is used as th
1a8b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1a8c0 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 er. The 5th par
1a8d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ameter to the.**
1a8e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1a8f0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 back is the name
1a900 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
1a910 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 ("main", "temp"
1a920 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 ,.** etc.) if ap
1a930 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 plicable. The 6
1a940 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
1a950 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1a960 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 allback.** is th
1a970 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e e name of the in
1a980 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 ner-most trigger
1a990 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 or view that is
1a9a0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
1a9b0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 .** the access a
1a9c0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
1a9d0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
1a9e0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
1a9f0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 y from.** top-le
1aa00 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a vel SQL code..**
1aa10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1aa20 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54 **.** {H12551} T
1aa30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1aa40 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 ter to an.**
1aa50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
1aa60 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
1aa70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1aa80 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e ack] shall be an
1aa90 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 integer.**
1aaa0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 [SQLITE_COP
1aab0 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 Y | authorizer c
1aac0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
1aad0 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a ies what action.
1aae0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 62 ** is b
1aaf0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e eing authorized.
1ab00 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 .**.** {H12552}
1ab10 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
1ab20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
1ab30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
1ab40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1ab50 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1ab60 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a ation callback].
1ab70 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
1ab80 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 l be parameters
1ab90 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e or NULL dependin
1aba0 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20 g on which.**
1abb0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 [SQLITE_C
1abc0 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 OPY | authorizer
1abd0 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 code] is used a
1abe0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
1abf0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ameter..**.** {H
1ac00 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 12553} The 5th p
1ac10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a arameter to the.
1ac20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1ac30 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1ac40 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
1ac50 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c callback] shall
1ac60 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 be the name.**
1ac70 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 of the
1ac80 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c database (exampl
1ac90 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 e: "main", "temp
1aca0 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ", etc.) if appl
1acb0 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 icable..**.** {H
1acc0 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 12554} The 6th p
1acd0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a arameter to the.
1ace0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1acf0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1ad00 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
1ad10 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c callback] shall
1ad20 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 be the name.**
1ad30 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 of the
1ad40 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
1ad50 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
1ad60 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
1ad70 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
1ad80 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 he access attemp
1ad90 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 t or NULL if thi
1ada0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 s access attempt
1adb0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f is directly fro
1adc0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f m.** to
1add0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 p-level SQL code
1ade0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ..*/./**********
1adf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1ae00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1ae10 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 3rd **********
1ae20 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 4th *********
1ae30 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 **/.#define SQLI
1ae40 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 TE_CREATE_INDEX
1ae50 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 1 /*
1ae60 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
1ae70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1ae80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ae90 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 E_CREATE_TABLE
1aea0 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 2 /* T
1aeb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1aec0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1aed0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1aee0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 _CREATE_TEMP_IND
1aef0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e EX 3 /* In
1af00 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
1af10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1af20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1af30 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c CREATE_TEMP_TABL
1af40 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 E 4 /* Tab
1af50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1af60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1af70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1af80 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 REATE_TEMP_TRIGG
1af90 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 ER 5 /* Trig
1afa0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
1afb0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1afc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1afd0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 EATE_TEMP_VIEW
1afe0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 6 /* View
1aff0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1b000 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1b010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1b020 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 ATE_TRIGGER
1b030 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 7 /* Trigge
1b040 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
1b050 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1b060 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1b070 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 TE_VIEW
1b080 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 8 /* View Na
1b090 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
1b0a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1b0b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 ine SQLITE_DELET
1b0c0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
1b0d0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 9 /* Table Na
1b0e0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1b0f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1b100 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 ne SQLITE_DROP_I
1b110 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 NDEX 1
1b120 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 0 /* Index Nam
1b130 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
1b140 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1b150 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 e SQLITE_DROP_TA
1b160 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 BLE 11
1b170 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1b180 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1b190 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b1a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
1b1b0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 P_INDEX 12
1b1c0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
1b1d0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
1b1e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b1f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
1b200 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 _TABLE 13
1b210 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1b220 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1b230 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b240 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
1b250 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 TRIGGER 14
1b260 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
1b270 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1b280 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b290 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 LITE_DROP_TEMP_V
1b2a0 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f IEW 15 /
1b2b0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
1b2c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b2d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b2e0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 ITE_DROP_TRIGGER
1b2f0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 16 /*
1b300 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
1b310 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1b320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b330 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 TE_DROP_VIEW
1b340 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 17 /*
1b350 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
1b360 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1b370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b380 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 E_INSERT
1b390 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 18 /* T
1b3a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1b3b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1b3c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b3d0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
1b3e0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 19 /* Pr
1b3f0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 agma Name 1s
1b400 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f t arg or NULL */
1b410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b420 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
1b430 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 20 /* Tab
1b440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
1b450 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
1b460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
1b470 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
1b480 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 21 /* NULL
1b490 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
1b4a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1b4b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
1b4c0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 ANSACTION
1b4d0 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 22 /* NULL
1b4e0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
1b4f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1b500 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 efine SQLITE_UPD
1b510 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ATE
1b520 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 23 /* Table
1b530 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
1b540 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1b550 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 fine SQLITE_ATTA
1b560 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
1b570 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 24 /* Filenam
1b580 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 e NULL
1b590 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1b5a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 ine SQLITE_DETAC
1b5b0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
1b5c0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 25 /* Database
1b5d0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 Name NULL
1b5e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1b5f0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f ne SQLITE_ALTER_
1b600 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
1b610 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6 /* Database
1b620 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d Name Table Nam
1b630 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1b640 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 e SQLITE_REINDEX
1b650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 27
1b660 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1b670 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1b680 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b690 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 SQLITE_ANALYZE
1b6a0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 28
1b6b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1b6c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b6d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b6e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 SQLITE_CREATE_VT
1b6f0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 ABLE 29
1b700 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1b710 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
1b720 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b730 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c QLITE_DROP_VTABL
1b740 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 E 30
1b750 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1b760 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
1b770 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b780 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 LITE_FUNCTION
1b790 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 31 /
1b7a0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
1b7b0 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 Function Name
1b7c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b7d0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 ITE_COPY
1b7e0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 0 /*
1b7f0 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 No longer used
1b800 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
1b810 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 EF: Tracing And
1b820 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 Profiling Functi
1b830 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 ons {H12280} <S6
1b840 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0400>.** EXPERIM
1b850 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ENTAL.**.** Thes
1b860 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 e routines regis
1b870 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e ter callback fun
1b880 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 ctions that can
1b890 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 be used for.** t
1b8a0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 racing and profi
1b8b0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 ling the executi
1b8c0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d on of SQL statem
1b8d0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ents..**.** The
1b8e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1b8f0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
1b900 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
1b910 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
1b920 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
1b930 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
1b940 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
1b950 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
1b960 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 ep()]..** The ca
1b970 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 llback returns a
1b980 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 UTF-8 rendering
1b990 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 of the SQL stat
1b9a0 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 ement text.** as
1b9b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 the statement f
1b9c0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 irst begins exec
1b9d0 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e uting. Addition
1b9e0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 al callbacks occ
1b9f0 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 ur.** as each tr
1ba00 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 iggered subprogr
1ba10 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 am is entered.
1ba20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f The callbacks fo
1ba30 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f r triggers.** co
1ba40 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 ntain a UTF-8 SQ
1ba50 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 L comment that i
1ba60 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 dentifies the tr
1ba70 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 igger..**.** The
1ba80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1ba90 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
1baa0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
1bab0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
1bac0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 as each SQL sta
1bad0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e tement finishes.
1bae0 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 The profile ca
1baf0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a llback contains.
1bb00 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ** the original
1bb10 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 statement text a
1bb20 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f nd an estimate o
1bb30 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d f wall-clock tim
1bb40 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 e.** of how long
1bb50 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
1bb60 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a took to run..**.
1bb70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1bb80 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54 68 *.** {H12281} Th
1bb90 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
1bba0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
1bbb0 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 y [sqlite3_trace
1bbc0 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()] .**
1bbd0 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 shall be invoke
1bbe0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 d.** wh
1bbf0 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 enever an SQL st
1bc00 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
1bc10 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 gins to execute
1bc20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
1bc30 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 whenever a trigg
1bc40 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 er subprogram fi
1bc50 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 rst begins to ru
1bc60 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 n..**.** {H12282
1bc70 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b } Each call to [
1bc80 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d sqlite3_trace()]
1bc90 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 shall override
1bca0 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a the previously.*
1bcb0 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 * regis
1bcc0 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c tered trace call
1bcd0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 back..**.** {H12
1bce0 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 283} A NULL trac
1bcf0 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c e callback shall
1bd00 20 64 69 73 61 62 6c 65 20 74 72 61 63 69 6e 67 disable tracing
1bd10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d ..**.** {H12284}
1bd20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
1bd30 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 ent to the trace
1bd40 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 callback shall
1bd50 62 65 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 be a copy of.**
1bd60 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 the poi
1bd70 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 nter which was t
1bd80 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
1bd90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 to [sqlite3_trac
1bda0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 e()]..**.** {H12
1bdb0 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 285} The second
1bdc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1bdd0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 trace callback i
1bde0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 s a.**
1bdf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1be00 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e UTF-8 string con
1be10 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 taining the orig
1be20 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 inal text.**
1be30 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c of the SQL
1be40 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 statement as it
1be50 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f was passed into
1be60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1be70 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 e_v2()].**
1be80 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 or the equiv
1be90 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c alent, or an SQL
1bea0 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 comment indicat
1beb0 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e ing the beginnin
1bec0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 g.** of
1bed0 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 a trigger subpr
1bee0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ogram..**.** {H1
1bef0 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 2287} The callba
1bf00 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
1bf10 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 stered by [sqlit
1bf20 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 e3_profile()] is
1bf30 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 invoked.**
1bf40 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51 4c as each SQL
1bf50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
1bf60 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 hes..**.** {H122
1bf70 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 88} The first pa
1bf80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 rameter to the p
1bf90 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
1bfa0 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 is a copy of.**
1bfb0 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72 64 the 3rd
1bfc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
1bfd0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
1bfe0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 ]..**.** {H12289
1bff0 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 } The second par
1c000 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 ameter to the pr
1c010 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 ofile callback i
1c020 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 s a.**
1c030 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1c040 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 UTF-8 string tha
1c050 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 t contains the c
1c060 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a omplete text of.
1c070 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
1c080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 SQL statement as
1c090 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 it was processe
1c0a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 d by [sqlite3_pr
1c0b0 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 epare_v2()].**
1c0c0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 or the e
1c0d0 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a quivalent..**.**
1c0e0 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20 74 68 {H12290} The th
1c0f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
1c100 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c the profile cal
1c110 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 lback is an esti
1c120 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 mate.**
1c130 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
1c140 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 f nanoseconds of
1c150 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 wall-clock time
1c160 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 required to.**
1c170 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 run the
1c180 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
1c190 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e rom start to fin
1c1a0 69 73 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ish..*/.SQLITE_E
1c1b0 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 XPERIMENTAL void
1c1c0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 *sqlite3_trace(
1c1d0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
1c1e0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f xTrace)(void*,co
1c1f0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 nst char*), void
1c200 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 *);.SQLITE_EXPER
1c210 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 IMENTAL void *sq
1c220 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 lite3_profile(sq
1c230 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 lite3*,. void(
1c240 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a *xProfile)(void*
1c250 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c ,const char*,sql
1c260 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f ite3_uint64), vo
1c270 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1c280 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f I3REF: Query Pro
1c290 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 gress Callbacks
1c2a0 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30 {H12910} <S60400
1c2b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
1c2c0 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 tine configures
1c2d0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
1c2e0 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f ion - the.** pro
1c2f0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d gress callback -
1c300 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 that is invoked
1c310 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
1c320 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e ring long.** run
1c330 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 ning calls to [s
1c340 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
1c350 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1c360 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
1c370 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 _get_table()].
1c380 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 An example use f
1c390 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 or this.** inter
1c3a0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 face is to keep
1c3b0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 a GUI updated du
1c3c0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 ring a large que
1c3d0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ry..**.** If the
1c3e0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
1c3f0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
1c400 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 ero, the operati
1c410 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 on is.** interru
1c420 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 pted. This feat
1c430 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ure can be used
1c440 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a to implement a.*
1c450 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f * "Cancel" butto
1c460 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 n on a GUI progr
1c470 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a ess dialog box..
1c480 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 **.** The progre
1c490 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 ss handler must
1c4a0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 not do anything
1c4b0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 that will modify
1c4c0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
1c4d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
1c4e0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f invoked the pro
1c4f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
1c500 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
1c510 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1c520 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1c530 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
1c540 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
1c550 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c560 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
1c570 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
1c580 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
1c590 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
1c5a0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 S:.**.** {H12911
1c5b0 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 } The callback f
1c5c0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
1c5d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
1c5e0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 ogress_handler()
1c5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
1c600 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
1c610 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
1c620 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
1c630 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
1c640 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
1c650 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20 54 **.** {H12912} T
1c660 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
1c670 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
1c680 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e once for every N
1c690 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 virtual.**
1c6a0 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 machine opc
1c6b0 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 odes, where N is
1c6c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
1c6d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 ment to.**
1c6e0 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 the [sqlite3
1c6f0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
1c700 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 r()] call that r
1c710 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 egistered.**
1c720 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 the callba
1c730 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65 73 ck. If N is les
1c740 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 s than 1, sqlite
1c750 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
1c760 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 er().**
1c770 20 61 63 74 73 20 61 73 20 69 66 20 61 20 4e 55 acts as if a NU
1c780 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 LL progress hand
1c790 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73 70 65 ler had been spe
1c7a0 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 cified..**.** {H
1c7b0 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72 12913} The progr
1c7c0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 ess callback its
1c7d0 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 elf is identifie
1c7e0 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a d by the third.*
1c7f0 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d * argum
1c800 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 ent to sqlite3_p
1c810 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
1c820 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 )..**.** {H12914
1c830 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 } The fourth arg
1c840 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
1c850 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
1c860 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 r() is a.**
1c870 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 void pointe
1c880 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 r passed to the
1c890 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 progress callbac
1c8a0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 k.** fu
1c8b0 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 nction each time
1c8c0 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a it is invoked..
1c8d0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20 49 **.** {H12915} I
1c8e0 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c f a call to [sql
1c8f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73 ite3_step()] res
1c900 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 ults in fewer th
1c910 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 an N opcodes.**
1c920 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 65 being e
1c930 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68 xecuted, then th
1c940 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
1c950 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 ack is never inv
1c960 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 oked..**.** {H12
1c970 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 916} Every call
1c980 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 to [sqlite3_prog
1c990 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a ress_handler()].
1c9a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 ** over
1c9b0 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 writes any previ
1c9c0 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 ously registered
1c9d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
1c9e0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 r..**.** {H12917
1c9f0 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 } If the progres
1ca00 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 s handler callba
1ca10 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 ck is NULL then
1ca20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 no progress.**
1ca30 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 handler
1ca40 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
1ca50 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74 68 * {H12918} If th
1ca60 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
1ca70 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 ack returns a re
1ca80 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 sult other than
1ca90 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 0, then.**
1caa0 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 the behavior
1cab0 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 is a if [sqlite
1cac0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 3_interrupt()] h
1cad0 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a ad been called..
1cae0 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33 30 ** <S30
1caf0 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 500>.*/.void sql
1cb00 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
1cb10 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 ndler(sqlite3*,
1cb20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 int, int(*)(void
1cb30 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a *), void*);../*.
1cb40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 ** CAPI3REF: Ope
1cb50 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 ning A New Datab
1cb60 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b ase Connection {
1cb70 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e H12700} <S40200>
1cb80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1cb90 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 tines open an SQ
1cba0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 Lite database fi
1cbb0 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 le whose name is
1cbc0 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a given by the.**
1cbd0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
1cbe0 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 nt. The filename
1cbf0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 argument is int
1cc00 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d erpreted as UTF-
1cc10 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 8 for.** sqlite3
1cc20 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
1cc30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e te3_open_v2() an
1cc40 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 d as UTF-16 in t
1cc50 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a he native byte.*
1cc60 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 * order for sqli
1cc70 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 te3_open16(). A
1cc80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1cc90 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 tion] handle is
1cca0 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 usually.** retur
1ccb0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 ned in *ppDb, ev
1ccc0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f en if an error o
1ccd0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 ccurs. The only
1cce0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 exception is th
1ccf0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 at.** if SQLite
1cd00 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
1cd10 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 ocate memory to
1cd20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 hold the [sqlite
1cd30 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 3] object,.** a
1cd40 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 NULL will be wri
1cd50 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 tten into *ppDb
1cd60 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 instead of a poi
1cd70 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c nter to the [sql
1cd80 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e ite3].** object.
1cd90 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
1cda0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f is opened (and/
1cdb0 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 or created) succ
1cdc0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a essfully, then.*
1cdd0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 * [SQLITE_OK] is
1cde0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
1cdf0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
1ce00 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
1ce10 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 d. The.** [sqli
1ce20 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 te3_errmsg()] or
1ce30 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1ce40 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 16()] routines c
1ce50 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 an be used to ob
1ce60 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 tain.** an Engli
1ce70 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 sh language desc
1ce80 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 ription of the e
1ce90 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rror..**.** The
1cea0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 default encoding
1ceb0 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
1cec0 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 e will be UTF-8
1ced0 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 if.** sqlite3_op
1cee0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
1cef0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c open_v2() is cal
1cf00 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 led and.** UTF-1
1cf10 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
1cf20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 byte order if sq
1cf30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 lite3_open16() i
1cf40 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 s used..**.** Wh
1cf50 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 ether or not an
1cf60 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 error occurs whe
1cf70 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 n it is opened,
1cf80 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 resources.** ass
1cf90 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
1cfa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1cfb0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 ction] handle sh
1cfc0 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 ould be released
1cfd0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 by.** passing i
1cfe0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c t to [sqlite3_cl
1cff0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 ose()] when it i
1d000 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 s no longer requ
1d010 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ired..**.** The
1d020 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1d030 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b ) interface work
1d040 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f s like sqlite3_o
1d050 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 pen().** except
1d060 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 that it accepts
1d070 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 two additional p
1d080 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 arameters for ad
1d090 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c ditional control
1d0a0 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 .** over the new
1d0b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1d0c0 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 tion. The flags
1d0d0 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74 parameter can t
1d0e0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 ake one of.** th
1d0f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 e following thre
1d100 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e e values, option
1d110 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 ally combined wi
1d120 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
1d130 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
1d140 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e or [SQLITE_OPEN
1d150 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 _FULLMUTEX] flag
1d160 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a s:.**.** <dl>.**
1d170 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 <dt>[SQLITE_OPE
1d180 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e N_READONLY]</dt>
1d190 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
1d1a0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 base is opened i
1d1b0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 n read-only mode
1d1c0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 . If the databa
1d1d0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 se does not.** a
1d1e0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e lready exist, an
1d1f0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
1d200 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
1d210 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
1d220 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a READWRITE]</dt>.
1d230 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
1d240 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
1d250 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 r reading and wr
1d260 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c iting if possibl
1d270 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a e, or reading.**
1d280 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c only if the fil
1d290 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 e is write prote
1d2a0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 cted by the oper
1d2b0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 ating system. I
1d2c0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 n either.** case
1d2d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 the database mu
1d2e0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 st already exist
1d2f0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 , otherwise an e
1d300 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
1d310 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
1d320 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
1d330 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
1d340 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c TE_OPEN_CREATE]<
1d350 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1d360 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1d370 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
1d380 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 nd writing, and
1d390 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66 is creates it if
1d3a0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 .** it does not
1d3b0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 already exist. T
1d3c0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 his is the behav
1d3d0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 ior that is alwa
1d3e0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 ys used for.** s
1d3f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
1d400 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 d sqlite3_open16
1d410 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c ().</dd>.** </dl
1d420 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 >.**.** If the 3
1d430 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
1d440 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1d450 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 ) is not one of
1d460 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 the.** combinati
1d470 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
1d480 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f or one of the co
1d490 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e mbinations shown
1d4a0 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a above combined.
1d4b0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ** with the [SQL
1d4c0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
1d4d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ] or [SQLITE_OPE
1d4e0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 N_FULLMUTEX] fla
1d4f0 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 gs,.** then the
1d500 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
1d510 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
1d520 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
1d530 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 _NOMUTEX] flag i
1d540 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 s set, then the
1d550 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1d560 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 ion.** opens in
1d570 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 the multi-thread
1d580 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
1d590 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ] as long as the
1d5a0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a single-thread.*
1d5b0 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 * mode has not b
1d5c0 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 een set at compi
1d5d0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
1d5e0 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a -time. If the.*
1d5f0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 * [SQLITE_OPEN_F
1d600 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 ULLMUTEX] flag i
1d610 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 s set then the d
1d620 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1d630 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 on opens.** in t
1d640 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 he serialized [t
1d650 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 hreading mode] u
1d660 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 nless single-thr
1d670 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 ead was.** previ
1d680 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 ously selected a
1d690 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
1d6a0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a r start-time..**
1d6b0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e .** If the filen
1d6c0 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a ame is ":memory:
1d6d0 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 ", then a privat
1d6e0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d e, temporary in-
1d6f0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a memory database.
1d700 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f ** is created fo
1d710 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
1d720 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 . This in-memor
1d730 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 y database will
1d740 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 vanish when.** t
1d750 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1d760 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
1d770 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
1d780 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
1d790 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f ht.** make use o
1d7a0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 f additional spe
1d7b0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 cial filenames t
1d7c0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 hat begin with t
1d7d0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 he ":" character
1d7e0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d ..** It is recom
1d7f0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e mended that when
1d800 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
1d810 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f name actually do
1d820 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a es begin with.**
1d830 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 a ":" character
1d840 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 you should pref
1d850 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 ix the filename
1d860 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 with a pathname
1d870 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 such as.** "./"
1d880 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 to avoid ambigui
1d890 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ty..**.** If the
1d8a0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 filename is an
1d8b0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
1d8c0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
1d8d0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
1d8e0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
1d8f0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 be created. Th
1d900 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
1d910 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
1d920 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
1d930 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
1d940 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1d950 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
1d960 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 d..**.** The fou
1d970 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
1d980 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1d990 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
1d9a0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
1d9b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
1d9c0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
1d9d0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
1d9e0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
1d9f0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
1da00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
1da10 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 ould use. If th
1da20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1da30 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 er is.** a NULL
1da40 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 pointer then the
1da50 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
1da60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 3_vfs] object is
1da70 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e used..**.** <b>
1da80 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 Note to Windows
1da90 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 users:</b> The
1daa0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f encoding used fo
1dab0 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 r the filename a
1dac0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 rgument.** of sq
1dad0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
1dae0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1daf0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 () must be UTF-8
1db00 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a , not whatever.*
1db10 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 * codepage is cu
1db20 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e rrently defined.
1db30 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 Filenames cont
1db40 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 aining internati
1db50 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 onal.** characte
1db60 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 rs must be conve
1db70 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 rted to UTF-8 pr
1db80 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 ior to passing t
1db90 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 hem into.** sqli
1dba0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
1dbb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
1dbc0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
1dbd0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 S:.**.** {H12701
1dbe0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f } The [sqlite3_o
1dbf0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
1dc00 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a _open16()], and.
1dc10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1dc20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
1dc30 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61 74 interfaces creat
1dc40 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 e a new.**
1dc50 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
1dc60 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 nnection] associ
1dc70 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 ated with.**
1dc80 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61 the databa
1dc90 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e se file given in
1dca0 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61 72 their first par
1dcb0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ameter..**.** {H
1dcc0 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 12702} The filen
1dcd0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
1dce0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
1dcf0 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 TF-8.**
1dd00 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 for [sqlite3_op
1dd10 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 en()] and [sqlit
1dd20 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e e3_open_v2()] an
1dd30 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 d as UTF-16.**
1dd40 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e in the n
1dd50 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
1dd60 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 for [sqlite3_op
1dd70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b en16()]..**.** {
1dd80 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 H12703} A succes
1dd90 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 sful invocation
1dda0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e of [sqlite3_open
1ddb0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1ddc0 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 en16()],.**
1ddd0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 or [sqlite3
1dde0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 _open_v2()] writ
1ddf0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 es a pointer to
1de00 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 a new.**
1de10 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e [database conn
1de20 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 ection] into *pp
1de30 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 Db..**.** {H1270
1de40 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 4} The [sqlite3_
1de50 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
1de60 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 3_open16()], and
1de70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1de80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
1de90 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 interfaces retu
1dea0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 rn [SQLITE_OK] u
1deb0 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 pon success,.**
1dec0 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61 or an a
1ded0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
1dee0 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 r code] on failu
1def0 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 re..**.** {H1270
1df00 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 6} The default t
1df10 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 ext encoding for
1df20 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 a new database
1df30 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a created using.**
1df40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1df50 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 e3_open()] or [s
1df60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1df70 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e ] will be UTF-8.
1df80 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20 .**.** {H12707}
1df90 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 The default text
1dfa0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 encoding for a
1dfb0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 new database cre
1dfc0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 ated using.**
1dfd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1dfe0 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 open16()] will b
1dff0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 e UTF-16..**.**
1e000 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71 {H12709} The [sq
1e010 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d lite3_open(F,D)]
1e020 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 interface is eq
1e030 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 uivalent to.**
1e040 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1e050 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 _open_v2(F,D,G,0
1e060 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 70 )] where the G p
1e070 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 arameter is.**
1e080 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
1e090 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c OPEN_READWRITE]|
1e0a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
1e0b0 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ATE]..**.** {H12
1e0c0 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 61 711} If the G pa
1e0d0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
1e0e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c te3_open_v2(F,D,
1e0f0 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 G,V)] contains t
1e100 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 he.** b
1e110 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 it value [SQLITE
1e120 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 _OPEN_READONLY]
1e130 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
1e140 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 e is opened.**
1e150 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64 for read
1e160 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ing only..**.**
1e170 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 65 20 {H12712} If the
1e180 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b G parameter to [
1e190 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1e1a0 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 F,D,G,V)] contai
1e1b0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ns the.**
1e1c0 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 bit value [SQ
1e1d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1e1e0 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61 ITE] then the da
1e1f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1e200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 .** rea
1e210 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
1e220 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 if possible, or
1e230 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c for reading onl
1e240 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 y if the.**
1e250 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 69 file is wri
1e260 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 te protected by
1e270 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
1e280 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 stem..**.** {H12
1e290 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 61 713} If the G pa
1e2a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
1e2b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c te3_open_v2(F,D,
1e2c0 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a G,V)] omits the.
1e2d0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 ** bit
1e2e0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 value [SQLITE_OP
1e2f0 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 EN_CREATE] and t
1e300 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
1e310 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 not.**
1e320 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 previously exis
1e330 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
1e340 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b eturned..**.** {
1e350 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 47 H12714} If the G
1e360 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
1e370 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 qlite3_open_v2(F
1e380 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e ,D,G,V)] contain
1e390 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
1e3a0 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c bit value [SQL
1e3b0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
1e3c0 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
1e3d0 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 e does not.**
1e3e0 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c previousl
1e3f0 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e y exist, then an
1e400 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 attempt is made
1e410 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a to create and.*
1e420 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 69 * initi
1e430 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 61 alize the databa
1e440 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 se..**.** {H1271
1e450 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 7} If the filena
1e460 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b me argument to [
1e470 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
1e480 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
1e490 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
1e4a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
1e4b0 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d n_v2()] is ":mem
1e4c0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 ory:", then an p
1e4d0 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 rivate,.**
1e4e0 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 ephemeral, i
1e4f0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
1e500 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 e is created for
1e510 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e the connection.
1e520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f .** <to
1e530 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 do>Is SQLITE_OPE
1e540 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f N_CREATE|SQLITE_
1e550 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 OPEN_READWRITE r
1e560 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 equired.**
1e570 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f in sqlite3_o
1e580 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e pen_v2()?</todo>
1e590 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20 .**.** {H12719}
1e5a0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
1e5b0 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d is NULL or an em
1e5c0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e pty string, then
1e5d0 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 a private,.**
1e5e0 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 ephemera
1e5f0 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 l on-disk databa
1e600 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 se will be creat
1e610 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ed..**
1e620 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f <todo>Is SQLITE_
1e630 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 OPEN_CREATE|SQLI
1e640 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
1e650 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 E required.**
1e660 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 in sqlite
1e670 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 3_open_v2()?</to
1e680 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 do>.**.** {H1272
1e690 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 1} The [database
1e6a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 connection] cre
1e6b0 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ated by [sqlite3
1e6c0 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 _open_v2(F,D,G,V
1e6d0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 )].** w
1e6e0 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71 6c ill use the [sql
1e6f0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
1e700 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
1e710 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c 0a he V parameter,.
1e720 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 ** or t
1e730 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
1e740 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
1e750 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 if V is a NULL p
1e760 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ointer..**.** {H
1e770 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 12723} Two [data
1e780 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
1e790 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20 63 ] will share a c
1e7a0 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 20 62 ommon cache if b
1e7b0 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 20 20 oth were.**
1e7c0 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 74 68 opened with
1e7d0 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 77 68 the same VFS wh
1e7e0 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 ile [shared cach
1e7f0 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 e mode] was enab
1e800 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 led and.**
1e810 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c 65 if both file
1e820 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65 71 names compare eq
1e830 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 ual using memcmp
1e840 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67 20 () after having
1e850 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 been.**
1e860 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74 68 processed by th
1e870 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c e [sqlite3_vfs |
1e880 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 xFullPathname]
1e890 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 56 46 method of the VF
1e8a0 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 S..*/.int sqlite
1e8b0 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 3_open(. const
1e8c0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 char *filename,
1e8d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
1e8e0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a lename (UTF-8) *
1e8f0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
1e900 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
1e910 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
1e920 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
1e930 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 qlite3_open16(.
1e940 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c const void *fil
1e950 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
1e960 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
1e970 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 TF-16) */. sqli
1e980 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
1e990 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
1e9a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
1e9b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
1e9c0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 pen_v2(. const
1e9d0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 char *filename,
1e9e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
1e9f0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a lename (UTF-8) *
1ea00 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
1ea10 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db, /* O
1ea20 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
1ea30 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c ndle */. int fl
1ea40 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 ags,
1ea50 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 /* Flags */.
1ea60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 const char *zVfs
1ea70 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 /* Name
1ea80 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f of VFS module to
1ea90 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a use */.);../*.*
1eaa0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f * CAPI3REF: Erro
1eab0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 r Codes And Mess
1eac0 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 ages {H12800} <S
1ead0 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60200>.**.** The
1eae0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
1eaf0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
1eb00 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 urns the numeric
1eb10 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f [result code] o
1eb20 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 r.** [extended r
1eb30 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 esult code] for
1eb40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
1eb50 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a failed sqlite3_*
1eb60 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 API call.** ass
1eb70 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b ociated with a [
1eb80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1eb90 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 ion]. If a prior
1eba0 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 API call failed
1ebb0 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 .** but the most
1ebc0 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c recent API call
1ebd0 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 succeeded, the
1ebe0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
1ebf0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 m.** sqlite3_err
1ec00 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 code() is undefi
1ec10 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ned. The sqlite
1ec20 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
1ec30 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 de().** interfac
1ec40 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 e is the same ex
1ec50 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 cept that it alw
1ec60 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 ays returns the
1ec70 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
1ec80 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 sult code] even
1ec90 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 when extended re
1eca0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a sult codes are.*
1ecb0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a * disabled..**.*
1ecc0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 * The sqlite3_er
1ecd0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 rmsg() and sqlit
1ece0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 e3_errmsg16() re
1ecf0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e turn English-lan
1ed00 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 guage.** text th
1ed10 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
1ed20 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 error, as eithe
1ed30 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
1ed40 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 6 respectively..
1ed50 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ** Memory to hol
1ed60 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 d the error mess
1ed70 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 age string is ma
1ed80 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 naged internally
1ed90 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
1eda0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 tion does not ne
1edb0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 ed to worry abou
1edc0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 t freeing the re
1edd0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 sult..** However
1ede0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 , the error stri
1edf0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 ng might be over
1ee00 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c written or deall
1ee10 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 ocated by.** sub
1ee20 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
1ee30 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
1ee40 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e terface function
1ee50 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 s..**.** When th
1ee60 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
1ee70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
1ee80 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 in use, it migh
1ee90 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 t be the.** case
1eea0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 that a second e
1eeb0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 rror occurs on a
1eec0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
1eed0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 in between.** t
1eee0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 he time of the f
1eef0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 irst error and t
1ef00 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 he call to these
1ef10 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
1ef20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e When that happen
1ef30 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 s, the second er
1ef40 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f ror will be repo
1ef50 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 rted since these
1ef60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
1ef70 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 lways report the
1ef80 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 most recent res
1ef90 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a ult. To avoid.*
1efa0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 * this, each thr
1efb0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 ead can obtain e
1efc0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 xclusive use of
1efd0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
1efe0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 nnection] D.** b
1eff0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 y invoking [sqli
1f000 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d te3_mutex_enter]
1f010 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
1f020 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 ex](D)) before b
1f030 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 eginning.** to u
1f040 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e se D and invokin
1f050 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
1f060 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 _leave]([sqlite3
1f070 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 _db_mutex](D)) a
1f080 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c fter.** all call
1f090 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 s to the interfa
1f0a0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 ces listed here
1f0b0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a are completed..*
1f0c0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 *.** If an inter
1f0d0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 face fails with
1f0e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 SQLITE_MISUSE, t
1f0f0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e hat means the in
1f100 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 terface.** was i
1f110 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 nvoked incorrect
1f120 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ly by the applic
1f130 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 ation. In that
1f140 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 case, the.** err
1f150 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
1f160 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e age may or may n
1f170 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a ot be set..**.**
1f180 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
1f190 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65 20 ** {H12801} The
1f1a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
1f1b0 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (D)] interface r
1f1c0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
1f1d0 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ic.** [
1f1e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
1f1f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
1f200 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d code] for the m
1f210 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 ost recently.**
1f220 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 failed
1f230 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 interface call a
1f240 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1f250 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1f260 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a nection] D..**.*
1f270 2a 20 7b 48 31 32 38 30 32 7d 20 54 68 65 20 5b * {H12802} The [
1f280 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
1f290 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 _errcode(D)] int
1f2a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
1f2b0 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 he numeric.**
1f2c0 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 [extended
1f2d0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f result code] fo
1f2e0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e r the most recen
1f2f0 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 tly.**
1f300 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 failed interface
1f310 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 call associated
1f320 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
1f330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1f340 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 D..**.** {H12803
1f350 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 } The [sqlite3_e
1f360 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 rrmsg(D)] and [s
1f370 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
1f380 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D)].**
1f390 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 interfaces retur
1f3a0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
1f3b0 67 65 20 74 65 78 74 20 74 68 61 74 20 64 65 73 ge text that des
1f3c0 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 cribes.**
1f3d0 20 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 the error in
1f3e0 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e the mostly recen
1f3f0 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 tly failed inter
1f400 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 face call,.**
1f410 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 encoded a
1f420 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
1f430 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 r UTF-16 respect
1f440 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ively..**.** {H1
1f450 32 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67 2807} The string
1f460 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
1f470 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1f480 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
1f490 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 rmsg16()].**
1f4a0 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 are valid
1f4b0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53 until the next S
1f4c0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 QLite interface
1f4d0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 call..**.** {H12
1f4e0 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 808} Calls to AP
1f4f0 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 I routines that
1f500 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e do not return an
1f510 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 error code.**
1f520 20 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65 (example
1f530 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f : [sqlite3_data_
1f540 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 count()]) do not
1f550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 .** cha
1f560 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f nge the error co
1f570 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65 de or message re
1f580 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 turned by.**
1f590 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 [sqlite3_e
1f5a0 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 rrcode()], [sqli
1f5b0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
1f5c0 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 code()],.**
1f5d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 [sqlite3_er
1f5e0 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c rmsg()], or [sql
1f5f0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
1f600 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d ..**.** {H12809}
1f610 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 Interfaces that
1f620 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 are not associa
1f630 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69 ted with a speci
1f640 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 fic.**
1f650 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1f660 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a tion] (examples:
1f670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1f680 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
1f690 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 or [sqlite3_ena
1f6a0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 ble_shared_cache
1f6b0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
1f6c0 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 do not change th
1f6d0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
1f6e0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 d by.**
1f6f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
1f700 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 e()], [sqlite3_e
1f710 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
1f720 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
1f730 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
1f740 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f )], or [sqlite3_
1f750 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a errmsg16()]..*/.
1f760 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
1f770 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
1f780 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
1f790 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 tended_errcode(s
1f7a0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e qlite3 *db);.con
1f7b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1f7c0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
1f7d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
1f7e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
1f7f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
1f800 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
1f810 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
1f820 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 {H13000} <H1301
1f830 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
1f840 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
1f850 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 ent} {prepared s
1f860 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a tatements}.**.**
1f870 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
1f880 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
1f890 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 esents a single
1f8a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a SQL statement..*
1f8b0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
1f8c0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e variously known
1f8d0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 as a "prepared
1f8e0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a statement" or a.
1f8f0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c ** "compiled SQL
1f900 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 statement" or s
1f910 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 imply as a "stat
1f920 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 ement"..**.** Th
1f930 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 e life of a stat
1f940 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 ement object goe
1f950 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 s something like
1f960 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
1f970 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
1f980 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
1f990 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
1f9a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 re_v2()] or a re
1f9b0 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 lated.** fu
1f9c0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 nction..** <li>
1f9d0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b Bind values to [
1f9e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d host parameters]
1f9f0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
1fa00 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
1fa10 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
1fa20 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
1fa30 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
1fa40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1fa50 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
1fa60 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
1fa70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 the statement u
1fa80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
1fa90 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 set()] then go b
1faa0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 ack.** to s
1fab0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 tep 2. Do this
1fac0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d zero or more tim
1fad0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 es..** <li> Dest
1fae0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 roy the object u
1faf0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
1fb00 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f nalize()]..** </
1fb10 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 ol>.**.** Refer
1fb20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e to documentation
1fb30 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d on individual m
1fb40 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 ethods above for
1fb50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
1fb60 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 nformation..*/.t
1fb70 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
1fb80 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 lite3_stmt sqlit
1fb90 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 e3_stmt;../*.**
1fba0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 CAPI3REF: Run-ti
1fbb0 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 me Limits {H1276
1fbc0 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S20600>.**.*
1fbd0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
1fbe0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 allows the size
1fbf0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 of various cons
1fc00 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d tructs to be lim
1fc10 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e ited.** on a con
1fc20 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 nection by conne
1fc30 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 ction basis. Th
1fc40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
1fc50 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 r is the.** [dat
1fc60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1fc70 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 ] whose limit is
1fc80 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 to be set or qu
1fc90 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 eried. The.** s
1fca0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1fcb0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c is one of the [l
1fcc0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d imit categories]
1fcd0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a that define a.*
1fce0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 * class of const
1fcf0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 ructs to be size
1fd00 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 limited. The t
1fd10 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
1fd20 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d s the.** new lim
1fd30 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 it for that cons
1fd40 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 truct. The func
1fd50 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
1fd60 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a old limit..**.*
1fd70 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d * If the new lim
1fd80 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 it is a negative
1fd90 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d number, the lim
1fda0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e it is unchanged.
1fdb0 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 .** For the limi
1fdc0 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 t category of SQ
1fdd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 LITE_LIMIT_XYZ t
1fde0 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20 75 here is a hard u
1fdf0 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 pper.** bound se
1fe00 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 t by a compile-t
1fe10 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 ime C preprocess
1fe20 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 or macro named S
1fe30 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a QLITE_MAX_XYZ..*
1fe40 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 * (The "_LIMIT_"
1fe50 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 in the name is
1fe60 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 changed to "_MAX
1fe70 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 _".).** Attempts
1fe80 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c to increase a l
1fe90 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 imit above its h
1fea0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 ard upper bound
1feb0 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 are.** silently
1fec0 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 truncated to the
1fed0 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 hard upper limi
1fee0 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d t..**.** Run tim
1fef0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 e limits are int
1ff00 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
1ff10 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 applications th
1ff20 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 at manage.** bot
1ff30 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 h their own inte
1ff40 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e rnal database an
1ff50 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 d also databases
1ff60 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f that are contro
1ff70 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 lled.** by untru
1ff80 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f sted external so
1ff90 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 urces. An examp
1ffa0 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d le application m
1ffb0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 ight be a.** web
1ffc0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 browser that has
1ffd0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 its own databas
1ffe0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 es for storing h
1fff0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 istory and.** se
20000 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 parate databases
20010 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a controlled by J
20020 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 avaScript applic
20030 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 ations downloade
20040 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 d.** off the Int
20050 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 ernet. The inte
20060 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 rnal databases c
20070 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a an be given the.
20080 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c ** large, defaul
20090 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 t limits. Datab
200a0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 ases managed by
200b0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
200c0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e can.** be given
200d0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 much smaller li
200e0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f mits designed to
200f0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 prevent a denia
20100 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 l of service.**
20110 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 attack. Develop
20120 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 ers might also w
20130 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b ant to use the [
20140 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
20150 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 orizer()].** int
20160 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 erface to furthe
20170 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 r control untrus
20180 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 ted SQL. The si
20190 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ze of the databa
201a0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 se.** created by
201b0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 an untrusted sc
201c0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 ript can be cont
201d0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a ained using the.
201e0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 ** [max_page_cou
201f0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a nt] [PRAGMA]..**
20200 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 .** New run-time
20210 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 limit categorie
20220 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
20230 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
20240 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 s..**.** INVARIA
20250 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 NTS:.**.** {H127
20260 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 62} A successful
20270 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
20280 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 3_limit(D,C,V)]
20290 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 where V is.**
202a0 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65 20 positive
202b0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69 changes the limi
202c0 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 t on the size of
202d0 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 construct C in
202e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
202f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
20300 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c tion] D to the l
20310 65 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74 esser of V and t
20320 68 65 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a he hard upper.**
20330 20 20 20 20 20 20 20 20 20 20 62 6f 75 6e 64 20 bound
20340 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 43 on the size of C
20350 20 74 68 61 74 20 69 73 20 73 65 74 20 61 74 20 that is set at
20360 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a compile-time..**
20370 0a 2a 2a 20 7b 48 31 32 37 36 36 7d 20 41 20 73 .** {H12766} A s
20380 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
20390 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 o [sqlite3_limit
203a0 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 (D,C,V)] where V
203b0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 is negative.**
203c0 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20 leaves
203d0 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 the state of the
203e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
203f0 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 ction] D unchang
20400 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 ed..**.** {H1276
20410 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 9} A successful
20420 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
20430 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 _limit(D,C,V)] r
20440 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 eturns the.**
20450 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 value of
20460 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 the limit on the
20470 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 size of constru
20480 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 ct C in the.**
20490 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 [databas
204a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
204b0 61 73 20 69 74 20 77 61 73 20 70 72 69 6f 72 20 as it was prior
204c0 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a to the call..*/.
204d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 int sqlite3_limi
204e0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
204f0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b id, int newVal);
20500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20510 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 : Run-Time Limit
20520 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32 Categories {H12
20530 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 790} <H12760>.**
20540 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 KEYWORDS: {limi
20550 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d t category} {lim
20560 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a it categories}.*
20570 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
20580 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 ants define vari
20590 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 ous aspects of a
205a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
205b0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 ction].** that c
205c0 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e an be limited in
205d0 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 size by calls t
205e0 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 o [sqlite3_limit
205f0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e ()]..** The mean
20600 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
20610 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 ous limits are a
20620 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
20630 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c <dl>.** <dt>SQL
20640 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
20650 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
20660 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 maximum size of
20670 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 any string or B
20680 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 LOB or table row
20690 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e .<dd>.**.** <dt>
206a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
206b0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
206c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
206d0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c length of an SQL
206e0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
206f0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
20700 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f E_LIMIT_COLUMN</
20710 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
20720 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
20730 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 columns in a ta
20740 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f ble definition o
20750 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 r in the.** resu
20760 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 lt set of a SELE
20770 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 CT or the maximu
20780 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
20790 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a mns in an index.
207a0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 ** or in an ORDE
207b0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 R BY or GROUP BY
207c0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a clause.</dd>.**
207d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
207e0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c IMIT_EXPR_DEPTH<
207f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
20800 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
20810 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 the parse tree
20820 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f on any expressio
20830 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
20840 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
20850 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f OMPOUND_SELECT</
20860 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
20870 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
20880 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 terms in a comp
20890 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 ound SELECT stat
208a0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ement.</dd>.**.*
208b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
208c0 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a IT_VDBE_OP</dt>.
208d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
208e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 um number of ins
208f0 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 tructions in a v
20900 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 irtual machine p
20910 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 rogram.** used t
20920 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 o implement an S
20930 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 QL statement.</d
20940 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
20950 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
20960 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c ON_ARG</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 61 72 67 75 6d 65 6e umber of argumen
20990 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e ts on a function
209a0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
209b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 >SQLITE_LIMIT_AT
209c0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c TACHED</dt>.** <
209d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
209e0 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 umber of attache
209f0 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 d databases.</dd
20a00 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
20a10 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
20a20 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 TTERN_LENGTH</dt
20a30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
20a40 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 imum length of t
20a50 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d he pattern argum
20a60 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 ent to the LIKE
20a70 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 or.** GLOB opera
20a80 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tors.</dd>.**.**
20a90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
20aa0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
20ab0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 R</dt>.** <dd>Th
20ac0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
20ad0 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e of variables in
20ae0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
20af0 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 t that can.** be
20b00 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 bound.</dd>.**
20b10 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
20b20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 SQLITE_LIMIT_LE
20b30 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
20b40 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
20b50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 e SQLITE_LIMIT_S
20b60 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 QL_LENGTH
20b70 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
20b80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
20b90 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 COLUMN
20ba0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 2.#def
20bb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
20bc0 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 _EXPR_DEPTH
20bd0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 3.#de
20be0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
20bf0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
20c00 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 T 4.#d
20c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
20c20 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 IT_VDBE_OP
20c30 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
20c40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
20c50 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
20c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
20c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
20c80 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 IMIT_ATTACHED
20c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 7
20ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20cb0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
20cc0 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 RN_LENGTH
20cd0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
20ce0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
20cf0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 NUMBER
20d00 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 9../*.** CAPI3R
20d10 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
20d20 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b SQL Statement {
20d30 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e H13010} <S10000>
20d40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
20d50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
20d60 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 piler}.**.** To
20d70 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 execute an SQL q
20d80 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 uery, it must fi
20d90 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 rst be compiled
20da0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 into a byte-code
20db0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e .** program usin
20dc0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 g one of these r
20dd0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
20de0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
20df0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 t, "db", is a [d
20e00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20e10 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f on] obtained fro
20e20 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c m a.** prior cal
20e30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 l to [sqlite3_op
20e40 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
20e50 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 open_v2()] or [s
20e60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
20e70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
20e80 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 nd argument, "zS
20e90 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 ql", is the stat
20ea0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
20eb0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a iled, encoded.**
20ec0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
20ed0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 or UTF-16. The
20ee0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
20ef0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
20f00 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 repare_v2().** i
20f10 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 nterfaces use UT
20f20 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 F-8, and sqlite3
20f30 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 _prepare16() and
20f40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
20f50 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 16_v2().** use U
20f60 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 TF-16..**.** If
20f70 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 the nByte argume
20f80 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 nt is less than
20f90 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 zero, then zSql
20fa0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
20fb0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 e.** first zero
20fc0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e terminator. If n
20fd0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
20fe0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 tive, then it is
20ff0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
21000 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 number of bytes
21010 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e read from zSql.
21020 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 When nByte is
21030 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
21040 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 e.** zSql string
21050 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 ends at either
21060 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 the first '\000'
21070 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 or '\u0000' cha
21080 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 racter or.** the
21090 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 nByte-th byte,
210a0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
210b0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 first. If the ca
210c0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 ller knows.** th
210d0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 at the supplied
210e0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 string is nul-te
210f0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 rminated, then t
21100 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a here is a small.
21110 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 ** performance a
21120 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 dvantage to be g
21130 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 ained by passing
21140 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 an nByte parame
21150 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 ter that.** is e
21160 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 qual to the numb
21170 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
21180 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 he input string
21190 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e <i>including</i>
211a0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d .** the nul-term
211b0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a inator bytes..**
211c0 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d .** *pzTail is m
211d0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
211e0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70 the first byte p
211f0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ast the end of t
21200 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 he.** first SQL
21210 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
21220 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e l. These routin
21230 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 es only compile
21240 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 the first.** sta
21250 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 tement in zSql,
21260 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 so *pzTail is le
21270 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 ft pointing to w
21280 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 hat remains.** u
21290 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a ncompiled..**.**
212a0 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 *ppStmt is left
212b0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 pointing to a c
212c0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 ompiled [prepare
212d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
212e0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 t can be.** exec
212f0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 uted using [sqli
21300 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 te3_step()]. If
21310 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 there is an err
21320 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 or, *ppStmt is s
21330 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 et.** to NULL.
21340 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 If the input tex
21350 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 t contains no SQ
21360 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 L (if the input
21370 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 is an empty.** s
21380 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 tring or a comme
21390 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 nt) then *ppStmt
213a0 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e is set to NULL.
213b0 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20 54 68 65 .** {A13018} The
213c0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 calling procedu
213d0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c re is responsibl
213e0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 e for deleting t
213f0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 he compiled.** S
21400 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 QL statement usi
21410 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
21420 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 lize()] after it
21430 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
21440 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 th it..**.** On
21450 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 success, [SQLITE
21460 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
21470 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b , otherwise an [
21480 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
21490 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
214a0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
214b0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 re_v2() and sqli
214c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
214d0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 () interfaces ar
214e0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e.** recommended
214f0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f for all new pro
21500 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f grams. The two o
21510 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 lder interfaces
21520 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 are retained.**
21530 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
21540 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 mpatibility, but
21550 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 their use is di
21560 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e scouraged..** In
21570 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
21580 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 aces, the prepar
21590 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
215a0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 that is returned
215b0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
215c0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e tmt] object) con
215d0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 tains a copy of
215e0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 the.** original
215f0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 SQL text. This c
21600 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 auses the [sqlit
21610 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 e3_step()] inter
21620 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 face to.** behav
21630 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 e a differently
21640 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a in two ways:.**.
21650 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a ** <ol>.** <li>.
21660 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 ** If the databa
21670 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 se schema change
21680 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 s, instead of re
21690 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
216a0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a SCHEMA] as it.**
216b0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 always used to
216c0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 do, [sqlite3_ste
216d0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 p()] will automa
216e0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
216f0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 e the SQL.** sta
21700 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 tement and try t
21710 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 o run it again.
21720 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 If the schema h
21730 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a as changed in.**
21740 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 a way that make
21750 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 s the statement
21760 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c no longer valid,
21770 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
21780 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 ] will still.**
21790 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 return [SQLITE_S
217a0 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c CHEMA]. But unl
217b0 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 ike the legacy b
217c0 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 ehavior, [SQLITE
217d0 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e _SCHEMA] is.** n
217e0 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 ow a fatal error
217f0 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 . Calling [sqli
21800 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
21810 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 ] again will not
21820 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 make the.** err
21830 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 or go away. Not
21840 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f e: use [sqlite3_
21850 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e errmsg()] to fin
21860 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 d the text.** of
21870 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 the parsing err
21880 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 or that results
21890 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 in an [SQLITE_SC
218a0 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a HEMA] return..**
218b0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
218c0 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 >.** When an err
218d0 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 or occurs, [sqli
218e0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
218f0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 return one of t
21900 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b he detailed.** [
21910 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 error codes] or
21920 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
21930 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 codes]. The leg
21940 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 acy behavior was
21950 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 that.** [sqlite
21960 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 3_step()] would
21970 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 only return a ge
21980 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 neric [SQLITE_ER
21990 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 ROR] result code
219a0 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c .** and you woul
219b0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 d have to make a
219c0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 second call to
219d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
219e0 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f ] in order.** to
219f0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c find the underl
21a00 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 ying cause of th
21a10 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 e problem. With
21a20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 the "v2" prepare
21a30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 .** interfaces,
21a40 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 the underlying r
21a50 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 eason for the er
21a60 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ror is returned
21a70 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 immediately..**
21a80 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a </li>.** </ol>.*
21a90 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
21aa0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d 20 .**.** {H13011}
21ab0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 The [sqlite3_pre
21ac0 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e pare(db,zSql,...
21ad0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 )] and.**
21ae0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 [sqlite3_prep
21af0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e are_v2(db,zSql,.
21b00 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 ..)] interfaces
21b10 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a interpret the.**
21b20 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69 text i
21b30 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 n their zSql par
21b40 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e ameter as UTF-8.
21b50 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d 20 .**.** {H13012}
21b60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 The [sqlite3_pre
21b70 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e pare16(db,zSql,.
21b80 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 ..)] and.**
21b90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 [sqlite3_pr
21ba0 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 epare16_v2(db,zS
21bb0 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 ql,...)] interfa
21bc0 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 ces interpret th
21bd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 e.** te
21be0 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c xt in their zSql
21bf0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 parameter as UT
21c00 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
21c10 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
21c20 2a 0a 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49 66 *.** {H13013} If
21c30 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
21c40 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
21c50 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 prepare_v2(db,zS
21c60 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a ql,nByte,...)].*
21c70 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 * and i
21c80 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c ts variants is l
21c90 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 ess than zero, t
21ca0 68 65 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a he SQL text is.*
21cb0 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64 20 * read
21cc0 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 from zSql is rea
21cd0 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 d up to the firs
21ce0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
21cf0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 r..**.** {H13014
21d00 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 } If the nByte a
21d10 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
21d20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 te3_prepare_v2(d
21d30 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e b,zSql,nByte,...
21d40 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 )].** a
21d50 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 nd its variants
21d60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
21d70 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 then at most nB
21d80 79 74 65 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a ytes bytes of.**
21d90 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74 65 SQL te
21da0 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 xt is read from
21db0 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 zSql..**.** {H13
21dc0 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 015} In [sqlite3
21dd0 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a _prepare_v2(db,z
21de0 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d Sql,N,P,pzTail)]
21df0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
21e00 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 s.** if
21e10 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 the zSql input
21e20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f text contains mo
21e30 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 re than one SQL
21e40 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 statement.**
21e50 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c and pzTail
21e60 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
21e70 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 en *pzTail is ma
21e80 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 de to point to t
21e90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 he.** f
21ea0 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 irst byte past t
21eb0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 he end of the fi
21ec0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e rst SQL statemen
21ed0 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 t in zSql..**
21ee0 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 <todo>Wha
21ef0 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 t does *pzTail p
21f00 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65 oint to if there
21f10 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e is one statemen
21f20 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 t?</todo>.**.**
21f30 7b 48 31 33 30 31 36 7d 20 41 20 73 75 63 63 65 {H13016} A succe
21f40 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
21f50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
21f60 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 2(db,zSql,N,ppSt
21f70 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 mt,...)].**
21f80 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 or one of i
21f90 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69 74 ts variants writ
21fa0 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 es into *ppStmt
21fb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e a pointer to a n
21fc0 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ew.** [
21fd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
21fe0 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 nt] or a pointer
21ff0 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c to NULL if zSql
22000 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 contains.**
22010 20 20 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74 nothing ot
22020 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 her than whitesp
22030 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e ace or comments.
22040 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d 20 .**.** {H13019}
22050 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 The [sqlite3_pre
22060 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 pare_v2()] inter
22070 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61 72 face and its var
22080 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 iants return.**
22090 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
220a0 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f _OK] or an appro
220b0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
220c0 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 de] upon failure
220d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31 7d ..**.** {H13021}
220e0 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 Before [sqlite3
220f0 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c _prepare(db,zSql
22100 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a ,nByte,ppStmt,pz
22110 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a Tail)] or its.**
22120 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61 6e varian
22130 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 ts returns an er
22140 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f ror (any value o
22150 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
22160 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 E_OK]),.**
22170 20 20 20 20 74 68 65 79 20 66 69 72 73 74 20 73 they first s
22180 65 74 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 et *ppStmt to NU
22190 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 LL..*/.int sqlit
221a0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 e3_prepare(. sq
221b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
221c0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
221d0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
221e0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
221f0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
22200 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
22210 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
22220 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
22230 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
22240 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
22250 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
22260 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
22270 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
22280 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
22290 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
222a0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
222b0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
222c0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
222d0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
222e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
222f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
22300 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
22310 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
22320 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
22330 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
22340 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
22350 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
22360 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
22370 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
22380 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
22390 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
223a0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
223b0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
223c0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
223d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
223e0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
223f0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
22400 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
22410 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
22420 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
22430 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 are16(. sqlite3
22440 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
22450 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
22460 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
22470 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
22480 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
22490 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
224a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
224b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
224c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
224d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
224e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
224f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
22500 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
22510 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
22520 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
22530 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
22540 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
22550 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
22560 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
22570 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 3_prepare16_v2(.
22580 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
22590 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
225a0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
225b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
225c0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
225d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
225e0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
225f0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
22600 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
22610 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
22620 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
22630 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
22640 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
22650 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
22660 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
22670 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
22680 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
22690 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
226a0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a of zSql */.);..
226b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
226c0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 Retrieving State
226d0 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30 30 ment SQL {H13100
226e0 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a } <H13000>.**.**
226f0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
22700 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 can be used to r
22710 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 etrieve a saved
22720 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 copy of the orig
22730 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 inal.** SQL text
22740 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 used to create
22750 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
22760 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 ement] if that s
22770 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 tatement was.**
22780 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 compiled using e
22790 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
227a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
227b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
227c0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16_v2()]..**.**
227d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
227e0 2a 20 7b 48 31 33 31 30 31 7d 20 49 66 20 74 68 * {H13101} If th
227f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
22800 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 ement] passed as
22810 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
22820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
22830 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 lite3_sql()] was
22840 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 compiled using
22850 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f either [sqlite3_
22860 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
22870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
22880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
22890 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c v2()], then [sql
228a0 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 ite3_sql()] retu
228b0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rns.**
228c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
228d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
228e0 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
228f0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 a UTF-8 renderi
22900 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ng.** o
22910 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 f the original S
22920 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a QL statement..**
22930 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49 66 20 .** {H13102} If
22940 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
22950 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 atement] passed
22960 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 as the argument
22970 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b to.** [
22980 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 sqlite3_sql()] w
22990 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e as compiled usin
229a0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
229b0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 3_prepare()] or.
229c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
229d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
229e0 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ], then [sqlite3
229f0 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 20 _sql()] returns
22a00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
22a10 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d 20 54 **.** {H13103} T
22a20 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e he string return
22a30 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 ed by [sqlite3_s
22a40 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20 ql(S)] is valid
22a50 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 until the.**
22a60 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
22a70 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 statement] S is
22a80 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73 deleted using [s
22a90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
22aa0 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 S)]..*/.const ch
22ab0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 ar *sqlite3_sql(
22ac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
22ad0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
22ae0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c I3REF: Dynamical
22af0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f ly Typed Value O
22b00 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c bject {H15000} <
22b10 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20200>.** KEYWO
22b20 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 RDS: {protected
22b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b sqlite3_value} {
22b40 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
22b50 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a te3_value}.**.**
22b60 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
22b70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
22b80 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 bject to represe
22b90 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a nt all values.**
22ba0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f that can be sto
22bb0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 red in a databas
22bc0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 e table. SQLite
22bd0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 uses dynamic typ
22be0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 ing.** for the v
22bf0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e alues it stores.
22c00 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 Values stored i
22c10 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
22c20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 objects.** can b
22c30 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 e integers, floa
22c40 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
22c50 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 s, strings, BLOB
22c60 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a s, or NULL..**.*
22c70 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c * An sqlite3_val
22c80 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 ue object may be
22c90 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 either "protect
22ca0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 ed" or "unprotec
22cb0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e ted"..** Some in
22cc0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
22cd0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
22ce0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 ite3_value. Oth
22cf0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a er interfaces.**
22d00 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 will accept eit
22d10 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 her a protected
22d20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
22d30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
22d40 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 .** Every interf
22d50 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 ace that accepts
22d60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 sqlite3_value a
22d70 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 rguments specifi
22d80 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 es.** whether or
22d90 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 not it requires
22da0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
22db0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a ite3_value..**.*
22dc0 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f * The terms "pro
22dd0 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 tected" and "unp
22de0 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 rotected" refer
22df0 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f to whether or no
22e00 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 t.** a mutex is
22e10 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 held. A interna
22e20 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 l mutex is held
22e30 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a for a protected.
22e40 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
22e50 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d object but no m
22e60 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
22e70 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a an unprotected.
22e80 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
22e90 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c object. If SQL
22ea0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
22eb0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 to be single-thr
22ec0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b eaded.** (with [
22ed0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
22ee0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 E=0] and with [s
22ef0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
22f00 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 e()] returning 0
22f10 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 ).** or if SQLit
22f20 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 e is run in one
22f30 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 of reduced mutex
22f40 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 modes .** [SQLI
22f50 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
22f60 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 THREAD] or [SQLI
22f70 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
22f80 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 HREAD].** then t
22f90 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 here is no disti
22fa0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
22fb0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
22fc0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
22fd0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
22fe0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 s and they can b
22ff0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e e used interchan
23000 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 geably. However
23010 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d ,.** for maximum
23020 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 code portabilit
23030 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e y it is recommen
23040 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
23050 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d tions.** still m
23060 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 ake the distinct
23070 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 ion between betw
23080 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
23090 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
230a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
230b0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e bjects even when
230c0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 not strictly re
230d0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
230e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
230f0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 objects that are
23100 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d passed as param
23110 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a eters into the.*
23120 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
23130 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e of [application
23140 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
23150 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 ctions] are prot
23160 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 ected..** The sq
23170 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
23180 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
23190 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
231a0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e n_value()] is un
231b0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e protected..** Un
231c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
231d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
231e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
231f0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 with.** [sqlite
23200 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
23210 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
23220 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ind_value()]..**
23230 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
23240 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 lue_blob | sqlit
23250 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d e3_value_type()]
23260 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e family of.** in
23270 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
23280 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
23290 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
232a0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
232b0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f uct Mem sqlite3_
232c0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
232d0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 PI3REF: SQL Func
232e0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
232f0 65 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 ect {H16001} <S2
23300 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0200>.**.** The
23310 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 context in which
23320 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e an SQL function
23330 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f executes is sto
23340 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c red in an.** sql
23350 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
23360 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 ect. A pointer
23370 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f to an sqlite3_co
23380 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 ntext object.**
23390 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 is always first
233a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 parameter to [ap
233b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
233c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
233d0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
233e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
233f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
23400 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 entation will pa
23410 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 ss this.** point
23420 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 er through into
23430 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
23440 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 3_result_int | s
23450 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d qlite3_result()]
23460 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 ,.** [sqlite3_ag
23470 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
23480 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 )], [sqlite3_use
23490 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 r_data()],.** [s
234a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
234b0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 b_handle()], [sq
234c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
234d0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 a()],.** and/or
234e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
234f0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 data()]..*/.type
23500 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
23510 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 e3_context sqlit
23520 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a e3_context;../*.
23530 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e ** CAPI3REF: Bin
23540 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 ding Values To P
23550 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
23560 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 ts {H13500} <S70
23570 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 300>.** KEYWORDS
23580 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 : {host paramete
23590 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 r} {host paramet
235a0 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d ers} {host param
235b0 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 eter name}.** KE
235c0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 YWORDS: {SQL par
235d0 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 ameter} {SQL par
235e0 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 ameters} {parame
235f0 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a ter binding}.**.
23600 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 ** In the SQL st
23610 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b rings input to [
23620 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
23630 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 v2()] and its va
23640 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 riants,.** liter
23650 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 als may be repla
23660 63 65 64 20 62 79 20 61 20 70 61 72 61 6d 65 74 ced by a paramet
23670 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 er in one of the
23680 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 se forms:.**.**
23690 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a <ul>.** <li> ?.
236a0 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a ** <li> ?NNN.**
236b0 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c <li> :VVV.** <
236c0 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 li> @VVV.** <li
236d0 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e > $VVV.** </ul>
236e0 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 .**.** In the pa
236f0 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 rameter forms sh
23700 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 own above NNN is
23710 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 an integer lite
23720 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 ral,.** and VVV
23730 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 is an alpha-nume
23740 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ric parameter na
23750 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f me. The values o
23760 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d f these.** param
23770 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c eters (also call
23780 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 ed "host paramet
23790 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 er names" or "SQ
237a0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a L parameters").*
237b0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 * can be set usi
237c0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
237d0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
237e0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a defined here..*
237f0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
23800 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
23810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
23820 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 routines is alwa
23830 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ys.** a pointer
23840 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
23850 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
23860 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 urned from.** [s
23870 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
23880 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 2()] or its vari
23890 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ants..**.** The
238a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
238b0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
238c0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 the SQL paramete
238d0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 r to be set..**
238e0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c The leftmost SQL
238f0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
23900 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 n index of 1. W
23910 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d hen the same nam
23920 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 ed.** SQL parame
23930 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 ter is used more
23940 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f than once, seco
23950 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
23960 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 t.** occurrences
23970 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 have the same i
23980 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 ndex as the firs
23990 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a t occurrence..**
239a0 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e The index for n
239b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 amed parameters
239c0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 can be looked up
239d0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
239e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
239f0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 meter_index()] A
23a00 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 PI if desired.
23a10 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 The index.** for
23a20 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 "?NNN" paramete
23a30 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 rs is the value
23a40 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e of NNN..** The N
23a50 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 NN value must be
23a60 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 between 1 and t
23a70 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 he [sqlite3_limi
23a80 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 t()].** paramete
23a90 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f r [SQLITE_LIMIT_
23aa0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
23ab0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a (default value:
23ac0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 999)..**.** The
23ad0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
23ae0 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 is the value to
23af0 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 bind to the para
23b00 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 meter..**.** In
23b10 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 those routines t
23b20 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 hat have a fourt
23b30 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 h argument, its
23b40 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
23b50 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
23b60 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 in the parameter
23b70 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 . To be clear:
23b80 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 the value is the
23b90 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 .** number of <u
23ba0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 >bytes</u> in th
23bb0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 e value, not the
23bc0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
23bd0 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 cters..** If the
23be0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
23bf0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 r is negative, t
23c00 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
23c10 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 string is.** th
23c20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
23c30 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
23c40 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
23c50 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 r..**.** The fif
23c60 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
23c70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
23c80 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 (), sqlite3_bind
23c90 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 _text(), and.**
23ca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
23cb0 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 t16() is a destr
23cc0 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 uctor used to di
23cd0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f spose of the BLO
23ce0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 B or.** string a
23cf0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 fter SQLite has
23d00 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 finished with it
23d10 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 . If the fifth a
23d20 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 rgument is.** th
23d30 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 e special value
23d40 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c [SQLITE_STATIC],
23d50 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 then SQLite ass
23d60 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
23d70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
23d80 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e in static, unman
23d90 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 aged space and d
23da0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
23db0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 be freed..** If
23dc0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
23dd0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 nt has the value
23de0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 [SQLITE_TRANSIE
23df0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c NT], then.** SQL
23e00 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 ite makes its ow
23e10 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
23e20 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 f the data immed
23e30 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a iately, before.*
23e40 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 * the sqlite3_bi
23e50 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 nd_*() routine r
23e60 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
23e70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a e sqlite3_bind_z
23e80 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e eroblob() routin
23e90 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f e binds a BLOB o
23ea0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a f length N that.
23eb0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 ** is filled wit
23ec0 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 h zeroes. A zer
23ed0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 oblob uses a fix
23ee0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d ed amount of mem
23ef0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 ory.** (just an
23f00 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 integer to hold
23f10 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 its size) while
23f20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 it is being proc
23f30 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c essed..** Zerobl
23f40 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 obs are intended
23f50 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 to serve as pla
23f60 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c ceholders for BL
23f70 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e OBs whose.** con
23f80 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 tent is later wr
23f90 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b itten using.** [
23fa0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
23fb0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 n | incremental
23fc0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e BLOB I/O] routin
23fd0 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 es..** A negativ
23fe0 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 e value for the
23ff0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 zeroblob results
24000 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 in a zero-lengt
24010 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 h BLOB..**.** Th
24020 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
24030 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 () routines must
24040 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 be called after
24050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
24060 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 pare_v2()] (and
24070 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 its variants) or
24080 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
24090 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 )] and.** before
240a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
240b0 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 ]..** Bindings a
240c0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 re not cleared b
240d0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 y the [sqlite3_r
240e0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e eset()] routine.
240f0 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 .** Unbound para
24100 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 meters are inter
24110 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a preted as NULL..
24120 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
24130 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
24140 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
24150 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 ss or an error c
24160 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 ode if.** anythi
24170 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 ng goes wrong.
24180 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 [SQLITE_RANGE] i
24190 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 s returned if th
241a0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 e parameter.** i
241b0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
241c0 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e ange. [SQLITE_N
241d0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 OMEM] is returne
241e0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 d if malloc() fa
241f0 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ils..** [SQLITE_
24200 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 MISUSE] might be
24210 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
24220 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
24230 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 called on a.** v
24240 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 irtual machine t
24250 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 hat is the wrong
24260 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 state or which
24270 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e has already been
24280 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 finalized..** D
24290 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 etection of misu
242a0 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 se is unreliable
242b0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
242c0 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e should not depen
242d0 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d d.** on SQLITE_M
242e0 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 ISUSE returns.
242f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 SQLITE_MISUSE is
24300 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 intended to ind
24310 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 icate a.** a log
24320 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 ic error in the
24330 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 application. Fu
24340 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
24350 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a SQLite might.**
24360 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 panic rather th
24370 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 an return SQLITE
24380 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 _MISUSE..**.** S
24390 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
243a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
243b0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 _count()],.** [s
243c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
243d0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 meter_name()], a
243e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 nd [sqlite3_bind
243f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
24400 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ()]..**.** INVAR
24410 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
24420 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20 73 3506} The [SQL s
24430 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
24440 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74 6f r] recognizes to
24450 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d kens of the form
24460 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22 3f s.** "?
24470 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 ", "?NNN", "$VVV
24480 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 ", ":VVV", and "
24490 40 56 56 56 22 20 61 73 20 53 51 4c 20 70 61 72 @VVV" as SQL par
244a0 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20 20 ameters,.**
244b0 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20 69 where NNN i
244c0 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f s any sequence o
244d0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64 69 f one or more di
244e0 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 gits.**
244f0 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 and where VVV i
24500 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f s any sequence o
24510 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61 6c f one or more al
24520 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 phanumeric.**
24530 20 20 20 20 20 20 20 63 68 61 72 61 63 74 65 72 character
24540 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e s or "::" option
24550 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ally followed by
24560 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 a string contai
24570 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ning.**
24580 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 no spaces and c
24590 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 ontained within
245a0 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a parentheses..**.
245b0 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54 68 65 20 ** {H13509} The
245c0 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 initial value of
245d0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 an SQL paramete
245e0 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a r is NULL..**.**
245f0 20 7b 48 31 33 35 31 32 7d 20 54 68 65 20 69 6e {H13512} The in
24600 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 dex of an "?" SQ
24610 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f L parameter is o
24620 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 ne larger than t
24630 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c he.** l
24640 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 argest index of
24650 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
24660 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 the left, or 1
24670 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 if.** t
24680 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 he "?" is the le
24690 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d ftmost SQL param
246a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 eter..**.** {H13
246b0 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 515} The index o
246c0 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 f an "?NNN" SQL
246d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
246e0 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a integer NNN..**
246f0 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20 54 68 65 .** {H13518} The
24700 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 index of an ":V
24710 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 VV", "$VVV", or
24720 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d "@VVV" SQL param
24730 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 eter is.**
24740 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 the same as
24750 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 the index of lef
24760 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63 65 tmost occurrence
24770 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a s of the same.**
24780 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 parame
24790 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 ter, or one more
247a0 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 than the larges
247b0 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c t index over all
247c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 .** par
247d0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c ameters to the l
247e0 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20 74 eft if this is t
247f0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 he first occurre
24800 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 nce.**
24810 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 of this paramete
24820 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 r, or 1 if this
24830 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 is the leftmost
24840 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
24850 20 7b 48 31 33 35 32 31 7d 20 54 68 65 20 5b 53 {H13521} The [S
24860 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
24870 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69 74 piler] fails wit
24880 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e h an [SQLITE_RAN
24890 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 GE].**
248a0 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 error if the ind
248b0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
248c0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 ameter is less t
248d0 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20 20 han 1.**
248e0 20 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 or greater tha
248f0 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 n the compile-ti
24900 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 me SQLITE_MAX_VA
24910 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a RIABLE_NUMBER.**
24920 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 parame
24930 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 ter..**.** {H135
24940 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 24} Calls to [sq
24950 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 lite3_bind_text
24960 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 | sqlite3_bind(S
24970 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 ,N,V,...)].**
24980 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 associate
24990 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 the value V wit
249a0 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 h all SQL parame
249b0 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a ters having an.*
249c0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 * index
249d0 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 of N in the [pr
249e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
249f0 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 ] S..**.** {H135
24a00 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 27} Calls to [sq
24a10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 lite3_bind_text
24a20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 | sqlite3_bind(S
24a30 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,N,...)].**
24a40 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 override pr
24a50 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 ior calls with t
24a60 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f he same values o
24a70 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a f S and N..**.**
24a80 20 7b 48 31 33 35 33 30 7d 20 42 69 6e 64 69 6e {H13530} Bindin
24a90 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 gs established b
24aa0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
24ab0 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 text | sqlite3_b
24ac0 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 ind(S,...)].**
24ad0 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20 persist
24ae0 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 across calls to
24af0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
24b00 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 )]..**.** {H1353
24b10 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 3} In calls to [
24b20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
24b30 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a b(S,N,V,L,D)],.*
24b40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
24b50 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c te3_bind_text(S,
24b60 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a N,V,L,D)], or.**
24b70 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
24b80 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 e3_bind_text16(S
24b90 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 ,N,V,L,D)] SQLit
24ba0 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 e binds the firs
24bb0 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 t L.**
24bc0 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f bytes of the BLO
24bd0 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e B or string poin
24be0 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 ted to by V, whe
24bf0 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 n L.**
24c00 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e is non-negative.
24c10 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d 20 .**.** {H13536}
24c20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
24c30 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 ite3_bind_text(S
24c40 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a ,N,V,L,D)] or.**
24c50 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
24c60 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 e3_bind_text16(S
24c70 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 ,N,V,L,D)] SQLit
24c80 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 e binds characte
24c90 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 rs.** f
24ca0 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 rom V through th
24cb0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 e first zero cha
24cc0 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 racter when L is
24cd0 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a negative..**.**
24ce0 20 7b 48 31 33 35 33 39 7d 20 49 6e 20 63 61 6c {H13539} In cal
24cf0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
24d00 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c ind_blob(S,N,V,L
24d10 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ,D)],.**
24d20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f [sqlite3_bind_
24d30 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d text(S,N,V,L,D)]
24d40 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 , or.**
24d50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
24d60 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 ext16(S,N,V,L,D)
24d70 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 ] when D is the
24d80 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 special.**
24d90 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 constant [SQ
24da0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 LITE_STATIC], SQ
24db0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 Lite assumes tha
24dc0 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a t the value V.**
24dd0 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c is hel
24de0 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 d in static unma
24df0 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74 naged space that
24e00 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 will not change
24e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 .** dur
24e20 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 ing the lifetime
24e30 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e of the binding.
24e40 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d 20 .**.** {H13542}
24e50 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
24e60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 ite3_bind_blob(S
24e70 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 ,N,V,L,D)],.**
24e80 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
24e90 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 _bind_text(S,N,V
24ea0 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 ,L,D)], or.**
24eb0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
24ec0 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c bind_text16(S,N,
24ed0 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 V,L,D)] when D i
24ee0 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a s the special.**
24ef0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 consta
24f00 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 nt [SQLITE_TRANS
24f10 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 IENT], the routi
24f20 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20 20 ne makes a.**
24f30 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20 63 private c
24f40 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75 65 opy of the value
24f50 20 56 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 V before it ret
24f60 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 urns..**.** {H13
24f70 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 545} In calls to
24f80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
24f90 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c lob(S,N,V,L,D)],
24fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
24fb0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
24fc0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a S,N,V,L,D)], or.
24fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
24fe0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
24ff0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 (S,N,V,L,D)] whe
25000 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72 n D is a pointer
25010 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
25020 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 a function, SQLi
25030 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 te invokes that
25040 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 function to dest
25050 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 roy the.**
25060 20 20 20 20 76 61 6c 75 65 20 56 20 61 66 74 65 value V afte
25070 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
25080 64 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c 75 d using the valu
25090 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 e V..**.** {H135
250a0 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 48} In calls to
250b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 [sqlite3_bind_ze
250c0 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d roblob(S,N,V,L)]
250d0 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 the value bound
250e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
250f0 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74 65 a BLOB of L byte
25100 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e s, or a zero-len
25110 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69 73 gth BLOB if L is
25120 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a negative..**.**
25130 20 7b 48 31 33 35 35 31 7d 20 49 6e 20 63 61 6c {H13551} In cal
25140 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
25150 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 ind_value(S,N,V)
25160 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e 74 ] the V argument
25170 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 may.**
25180 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70 72 be either a [pr
25190 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
251a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 value] object or
251b0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 an.**
251c0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
251d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
251e0 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ct..*/.int sqlit
251f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c e3_bind_blob(sql
25200 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
25210 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
25220 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 t n, void(*)(voi
25230 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 d*));.int sqlite
25240 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 3_bind_double(sq
25250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
25260 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 , double);.int s
25270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 qlite3_bind_int(
25280 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
25290 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 nt, int);.int sq
252a0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 lite3_bind_int64
252b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
252c0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 int, sqlite3_int
252d0 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 64);.int sqlite3
252e0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 _bind_null(sqlit
252f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
25300 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
25310 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
25320 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
25330 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f char*, int n, vo
25340 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
25350 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
25360 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
25370 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
25380 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
25390 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
253a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 t sqlite3_bind_v
253b0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
253c0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 t*, int, const s
253d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
253e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
253f0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
25400 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
25410 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t n);../*.** CAP
25420 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 I3REF: Number Of
25430 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 SQL Parameters
25440 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 {H13600} <S70300
25450 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
25460 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 tine can be used
25470 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
25480 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 ber of [SQL para
25490 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 meters].** in a
254a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
254b0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d ent]. SQL param
254c0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 eters are tokens
254d0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 of the.** form
254e0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 "?", "?NNN", ":A
254f0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 AA", "$AAA", or
25500 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 "@AAA" that serv
25510 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c e as.** placehol
25520 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 ders for values
25530 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 that are [sqlite
25540 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 3_bind_blob | bo
25550 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 und].** to the p
25560 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c arameters at a l
25570 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a ater time..**.**
25580 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 This routine ac
25590 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 tually returns t
255a0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
255b0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f largest (rightmo
255c0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 st).** parameter
255d0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 . For all forms
255e0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 except ?NNN, thi
255f0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e s will correspon
25600 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 d to the.** numb
25610 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 er of unique par
25620 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 ameters. If par
25630 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f ameters of the ?
25640 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a NNN are used,.**
25650 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 there may be ga
25660 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a ps in the list..
25670 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
25680 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
25690 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
256a0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
256b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
256c0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ame()], and.** [
256d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
256e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
256f0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
25700 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 S:.**.** {H13601
25710 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 } The [sqlite3_b
25720 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
25730 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 unt(S)] interfac
25740 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 e returns.**
25750 20 20 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 the larges
25760 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 t index of all S
25770 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e QL parameters in
25780 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
25790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
257a0 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 ment] S, or 0 if
257b0 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 S contains no S
257c0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a QL parameters..*
257d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 /.int sqlite3_bi
257e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
257f0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
25800 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
25810 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f EF: Name Of A Ho
25820 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 st Parameter {H1
25830 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3620} <S70300>.*
25840 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
25850 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
25860 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 ter to the name
25870 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b of the n-th.** [
25880 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 SQL parameter] i
25890 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
258a0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c atement]..** SQL
258b0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
258c0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f he form "?NNN" o
258d0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 r ":AAA" or "@AA
258e0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 A" or "$AAA".**
258f0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 have a name whic
25900 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 h is the string
25910 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 "?NNN" or ":AAA"
25920 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 or "@AAA" or "$
25930 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 AAA".** respecti
25940 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 vely..** In othe
25950 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 r words, the ini
25960 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 tial ":" or "$"
25970 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a or "@" or "?".**
25980 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 is included as
25990 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 part of the name
259a0 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 ..** Parameters
259b0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 of the form "?"
259c0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 without a follow
259d0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 ing integer have
259e0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 no name.** and
259f0 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 are also referre
25a00 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f d to as "anonymo
25a10 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a us parameters"..
25a20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
25a30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 host parameter h
25a40 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
25a50 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 , not 0..**.** I
25a60 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 f the value n is
25a70 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 out of range or
25a80 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 if the n-th par
25a90 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d ameter is.** nam
25aa0 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c eless, then NULL
25ab0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
25ac0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
25ad0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 ng is.** always
25ae0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e in UTF-8 encodin
25af0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 g even if the na
25b00 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 med parameter wa
25b10 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 s.** originally
25b20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 specified as UTF
25b30 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f -16 in [sqlite3_
25b40 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a prepare16()] or.
25b50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
25b60 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
25b70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
25b80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
25b90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
25ba0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
25bb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
25bc0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
25bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
25be0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
25bf0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
25c00 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d 20 .**.** {H13621}
25c10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e The [sqlite3_bin
25c20 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
25c30 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
25c40 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 returns.**
25c50 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e a UTF-8 ren
25c60 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 dering of the na
25c70 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 me of the SQL pa
25c80 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 rameter in.**
25c90 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 the [prep
25ca0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
25cb0 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e S having index N
25cc0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 , or.**
25cd0 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 NULL if there i
25ce0 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 s no SQL paramet
25cf0 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 er with index N
25d00 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 or if the.**
25d10 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 parameter
25d20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 with index N is
25d30 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 an anonymous par
25d40 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 ameter "?"..*/.c
25d50 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
25d60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
25d70 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 r_name(sqlite3_s
25d80 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a tmt*, int);../*.
25d90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 ** CAPI3REF: Ind
25da0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 ex Of A Paramete
25db0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e r With A Given N
25dc0 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 ame {H13640} <S7
25dd0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 0300>.**.** Retu
25de0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 rn the index of
25df0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 an SQL parameter
25e00 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e given its name.
25e10 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 The.** index v
25e20 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 alue returned is
25e30 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 suitable for us
25e40 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a e as the second.
25e50 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
25e60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
25e70 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
25e80 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 )]. A zero.** i
25e90 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f s returned if no
25ea0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 matching parame
25eb0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 ter is found. T
25ec0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
25ed0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
25ee0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
25ef0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
25f00 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
25f10 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
25f20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
25f30 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
25f40 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
25f50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
25f60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
25f70 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
25f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
25f90 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
25fa0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
25fb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
25fc0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
25fd0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
25fe0 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20 54 **.** {H13641} T
25ff0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
26000 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
26010 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
26020 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 returns.**
26030 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f the index o
26040 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 f SQL parameter
26050 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
26060 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 statement].**
26070 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20 S whose
26080 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65 name matches the
26090 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c UTF-8 string N,
260a0 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69 or 0 if there i
260b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f s.** no
260c0 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 match..*/.int s
260d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
260e0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 meter_index(sqli
260f0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 te3_stmt*, const
26100 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a char *zName);..
26110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
26120 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e Reset All Bindin
26130 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 gs On A Prepared
26140 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 Statement {H136
26150 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 60} <S70300>.**.
26160 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 ** Contrary to t
26170 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
26180 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
26190 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
261a0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
261b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
261c0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
261d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
261e0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 ement]..** Use t
261f0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 his routine to r
26200 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
26210 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
26220 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
26230 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 TS:.**.** {H1366
26240 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
26250 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 clear_bindings(S
26260 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
26270 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 ets all SQL.**
26280 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 paramete
26290 72 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 r bindings in th
262a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
262b0 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f ement] S back to
262c0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 NULL..*/.int sq
262d0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
262e0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
262f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
26300 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
26310 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 Columns In A Res
26320 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d ult Set {H13710}
26330 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10700>.**.**
26340 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 Return the numbe
26350 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
26360 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 the result set r
26370 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a eturned by the.*
26380 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
26390 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 ement]. This rou
263a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 tine returns 0 i
263b0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
263c0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 L.** statement t
263d0 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 hat does not ret
263e0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 urn data (for ex
263f0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 ample an [UPDATE
26400 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ])..**.** INVARI
26410 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ANTS:.**.** {H13
26420 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 711} The [sqlite
26430 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 3_column_count(S
26440 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
26450 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
26460 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 of.** c
26470 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
26480 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 sult set generat
26490 65 64 20 62 79 20 74 68 65 20 5b 70 72 65 70 61 ed by the [prepa
264a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
264b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
264c0 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 0 if S does not
264d0 20 67 65 6e 65 72 61 74 65 20 61 20 72 65 73 75 generate a resu
264e0 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 lt set..*/.int s
264f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
26500 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
26510 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
26520 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d CAPI3REF: Colum
26530 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 n Names In A Res
26540 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d ult Set {H13720}
26550 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10700>.**.**
26560 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
26570 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 eturn the name a
26580 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 ssigned to a par
26590 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a ticular column.*
265a0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 * in the result
265b0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
265c0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 ] statement. Th
265d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
265e0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 _name().** inter
265f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
26600 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f ointer to a zero
26610 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
26620 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 8 string.** and
26630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
26640 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 ame16() returns
26650 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
26660 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
26670 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e * UTF-16 string.
26680 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
26690 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 meter is the [pr
266a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
266b0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d ].** that implem
266c0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 ents the [SELECT
266d0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 ] statement. The
266e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
266f0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r is the.** colu
26700 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 mn number. The
26710 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 leftmost column
26720 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a is number 0..**.
26730 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 ** The returned
26740 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 string pointer i
26750 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 s valid until ei
26760 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 ther the [prepar
26770 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
26780 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 is destroyed by
26790 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
267a0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 ze()] or until t
267b0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a he next call to.
267c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
267d0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 n_name() or sqli
267e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
267f0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 6() on the same
26800 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 column..**.** If
26810 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
26820 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 ) fails during t
26830 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 he processing of
26840 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a either routine.
26850 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ** (for example
26860 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 during a convers
26870 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 ion from UTF-8 t
26880 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 o UTF-16) then a
26890 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
268a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
268b0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
268c0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 a result column
268d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
268e0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 the "AS" clause
268f0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 for.** that colu
26900 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 mn, if there is
26910 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 an AS clause. I
26920 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 f there is no AS
26930 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 clause.** then
26940 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
26950 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 column is unspec
26960 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 ified and may ch
26970 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 ange from.** one
26980 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
26990 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a te to the next..
269a0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
269b0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31 7d :.**.** {H13721}
269c0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e A successful in
269d0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 vocation of the
269e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
269f0 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 name(S,N)].**
26a00 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 interface
26a10 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d returns the nam
26a20 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c e of the Nth col
26a30 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a umn (where 0 is.
26a40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
26a50 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 leftmost column)
26a60 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 for the result
26a70 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 set of the.**
26a80 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
26a90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 statement] S as
26aa0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
26ab0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e ed UTF-8 string.
26ac0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d 20 .**.** {H13723}
26ad0 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 A successful inv
26ae0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b ocation of the [
26af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
26b00 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 ame16(S,N)].**
26b10 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
26b20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 e returns the na
26b30 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f me of the Nth co
26b40 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 lumn (where 0 is
26b50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
26b60 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
26b70 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 ) for the result
26b80 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 set of the.**
26b90 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
26ba0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 d statement] S a
26bb0 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 s a zero-termina
26bc0 74 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e ted UTF-16 strin
26bd0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e g.** in
26be0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
26bf0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 order..**.** {H
26c00 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 13724} The [sqli
26c10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
26c20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
26c30 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d column_name16()]
26c40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
26c50 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 erfaces return a
26c60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
26c70 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 they are unable
26c80 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
26c90 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
26ca0 74 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f to hold their no
26cb0 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 rmal return stri
26cc0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ngs..**.** {H137
26cd0 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 25} If the N par
26ce0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
26cf0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 e3_column_name(S
26d00 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 ,N)] or.**
26d10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c [sqlite3_col
26d20 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d umn_name16(S,N)]
26d30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
26d40 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 , then the.**
26d50 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 interface
26d60 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 s return a NULL
26d70 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b pointer..**.** {
26d80 48 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 H13726} The stri
26d90 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
26da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
26db0 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a name(S,N)] and.*
26dc0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
26dd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
26de0 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 6(S,N)] are vali
26df0 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 d until the next
26e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
26e10 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 l to either rout
26e20 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d ine with the sam
26e30 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 e S and N parame
26e40 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ters.**
26e50 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 or until [sqlit
26e60 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 e3_finalize(S)]
26e70 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a is called..**.**
26e80 20 7b 48 31 33 37 32 37 7d 20 57 68 65 6e 20 61 {H13727} When a
26e90 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f result column o
26ea0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 f a [SELECT] sta
26eb0 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a tement contains.
26ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 ** an A
26ed0 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 S clause, the na
26ee0 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d me of that colum
26ef0 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74 69 66 n is the identif
26f00 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ier.**
26f10 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20 to the right of
26f20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a the AS keyword..
26f30 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
26f40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
26f50 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
26f60 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 , int N);.const
26f70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
26f80 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 lumn_name16(sqli
26f90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
26fa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26fb0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 EF: Source Of Da
26fc0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 ta In A Query Re
26fd0 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 sult {H13740} <S
26fe0 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 10700>.**.** The
26ff0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 se routines prov
27000 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 ide a means to d
27010 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f etermine what co
27020 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 lumn of what.**
27030 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 table in which d
27040 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 atabase a result
27050 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 of a [SELECT] s
27060 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 tatement comes f
27070 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 rom..** The name
27080 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
27090 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
270a0 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
270b0 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
270c0 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d a UTF-8 or UTF-
270d0 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 16 string. The
270e0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 _database_ routi
270f0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 nes return.** th
27100 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c e database name,
27110 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 the _table_ rou
27120 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
27130 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 table name, and
27140 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 .** the origin_
27150 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
27160 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e the column name.
27170 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 .** The returned
27180 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 string is valid
27190 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 until the [prep
271a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
271b0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 is destroyed.**
271c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
271d0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
271e0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 til the same inf
271f0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 ormation is requ
27200 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 ested.** again i
27210 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e n a different en
27220 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 coding..**.** Th
27230 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 e names returned
27240 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 are the origina
27250 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d l un-aliased nam
27260 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 es of the.** dat
27270 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
27280 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 d column..**.**
27290 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
272a0 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 nt to the follow
272b0 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b ing calls is a [
272c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
272d0 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 nt]..** These fu
272e0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 nctions return i
272f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
27300 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
27310 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
27320 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
27330 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
27340 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
27350 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ument..**.** If
27360 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 the Nth column r
27370 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 eturned by the s
27380 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 tatement is an e
27390 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 xpression or.**
273a0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 subquery and is
273b0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c not a column val
273c0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 ue, then all of
273d0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
273e0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 return.** NULL.
273f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d These routine m
27400 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e ight also return
27410 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 NULL if a memor
27420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
27430 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f or.** occurs. O
27440 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 therwise, they r
27450 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f eturn the name o
27460 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 f the attached d
27470 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a atabase, table.*
27480 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 * and column tha
27490 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 t query result c
274a0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 olumn was extrac
274b0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 ted from..**.**
274c0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 As with all othe
274d0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 r SQLite APIs, t
274e0 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 hose postfixed w
274f0 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
27500 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
27510 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f d strings, the o
27520 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
27530 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e eturn UTF-8. {EN
27540 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 D}.**.** These A
27550 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 PIs are only ava
27560 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 ilable if the li
27570 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c brary was compil
27580 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
27590 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
275a0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 LUMN_METADATA] C
275b0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
275c0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a mbol defined..**
275d0 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 .** {A13751}.**
275e0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
275f0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
27600 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 or more of these
27610 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 routines agains
27620 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 t the same.** pr
27630 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27640 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 and column at t
27650 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
27660 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
27670 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a e.** undefined..
27680 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
27690 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 31 7d :.**.** {H13741}
276a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
276b0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
276c0 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 me(S,N)] interfa
276d0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 ce returns eithe
276e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
276f0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 e UTF-8 zero-ter
27700 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 minated name of
27710 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f the database fro
27720 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 m which the.**
27730 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 Nth resu
27740 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 lt column of the
27750 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
27760 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 ment] S is extra
27770 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 cted,.**
27780 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 or NULL if the
27790 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 Nth column of S
277a0 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 is a general ex
277b0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 pression.**
277c0 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c or if unabl
277d0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
277e0 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 mory to store th
277f0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 e name..**.** {H
27800 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 13742} The [sqli
27810 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
27820 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d ase_name16(S,N)]
27830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
27840 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 ns either.**
27850 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 the UTF-16
27860 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
27870 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 er zero-terminat
27880 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 ed name of the d
27890 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 atabase.**
278a0 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 from which t
278b0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f he Nth result co
278c0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 lumn of the [pre
278d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
278e0 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 S is.**
278f0 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 extracted, or
27900 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 NULL if the Nth
27910 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 column of S is a
27920 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 general express
27930 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
27940 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 or if unable to
27950 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
27960 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d to store the nam
27970 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 e..**.** {H13743
27980 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
27990 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
279a0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
279b0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a returns either.
279c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
279d0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
279e0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 nated name of th
279f0 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 e table from whi
27a00 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ch the.**
27a10 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f Nth result co
27a20 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 lumn of the [pre
27a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27a40 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c S is extracted,
27a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
27a60 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 NULL if the Nth
27a70 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 column of S is a
27a80 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 general express
27a90 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
27aa0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 or if unable to
27ab0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
27ac0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d to store the nam
27ad0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 e..**.** {H13744
27ae0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
27af0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
27b00 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 16(S,N)] interfa
27b10 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 ce returns eithe
27b20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
27b30 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 e UTF-16 native
27b40 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d byte order zero-
27b50 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 terminated name
27b60 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 of the table.**
27b70 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 from wh
27b80 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 ich the Nth resu
27b90 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 lt column of the
27ba0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
27bb0 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 ment] S is.**
27bc0 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65 64 extracted
27bd0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 , or NULL if the
27be0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 Nth column of S
27bf0 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 is a general ex
27c00 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 pression.**
27c10 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c or if unabl
27c20 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
27c30 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 mory to store th
27c40 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 e name..**.** {H
27c50 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 13745} The [sqli
27c60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
27c70 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 n_name(S,N)] int
27c80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
27c90 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
27ca0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f the UTF-8 zero
27cb0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 -terminated name
27cc0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f of the table co
27cd0 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 lumn from which
27ce0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
27cf0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d Nth result colum
27d00 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 n of the [prepar
27d10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
27d20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a is extracted,.**
27d30 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c or NUL
27d40 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c L if the Nth col
27d50 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 umn of S is a ge
27d60 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e neral expression
27d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
27d80 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c if unable to all
27d90 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 ocate memory to
27da0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a store the name..
27db0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 36 7d 20 54 **.** {H13746} T
27dc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
27dd0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 mn_origin_name16
27de0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
27df0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a returns either.
27e00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
27e10 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
27e20 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 te order zero-te
27e30 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 rminated name of
27e40 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 the table.**
27e50 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72 column fr
27e60 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 om which the Nth
27e70 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f result column o
27e80 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
27e90 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
27ea0 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 ement] S is extr
27eb0 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 acted, or NULL i
27ec0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
27ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 .** of
27ee0 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 S is a general e
27ef0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 xpression or if
27f00 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
27f10 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 te memory.**
27f20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 to store t
27f30 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b he name..**.** {
27f40 48 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 H13748} The retu
27f50 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a rn values from.*
27f60 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
27f70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
27f80 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d ase_name | colum
27f90 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 n metadata inter
27fa0 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 faces].**
27fb0 20 20 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 are valid for
27fc0 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 the lifetime of
27fd0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
27fe0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 tatement].**
27ff0 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 or until t
28000 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 he encoding is c
28010 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65 hanged by anothe
28020 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 r metadata.**
28030 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 interface
28040 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 call for the sa
28050 6d 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 me prepared stat
28060 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e ement and column
28070 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 ..**.** ASSUMPTI
28080 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 ONS:.**.** {A137
28090 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 51} If two or mo
280a0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 re threads call
280b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 one or more.**
280c0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
280d0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
280e0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
280f0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
28100 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 es].**
28110 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 for the same [pr
28120 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28130 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c ] and result col
28140 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 umn.**
28150 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
28160 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
28170 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
28180 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
28190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
281a0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c atabase_name(sql
281b0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
281c0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
281d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
281e0 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 base_name16(sqli
281f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
28200 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
28210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
28220 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
28230 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
28240 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
28250 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 lumn_table_name1
28260 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
28270 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
28280 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
28290 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c _origin_name(sql
282a0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
282b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
282c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
282d0 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 in_name16(sqlite
282e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
282f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
28300 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 eclared Datatype
28310 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 Of A Query Resu
28320 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 lt {H13760} <S10
28330 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 700>.**.** The f
28340 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
28350 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
28360 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 atement]..** If
28370 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 this statement i
28380 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 s a [SELECT] sta
28390 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e tement and the N
283a0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
283b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 .** returned res
283c0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 ult set of that
283d0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 [SELECT] is a ta
283e0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 ble column (not
283f0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
28400 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 or subquery) th
28410 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 en the declared
28420 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
28430 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 e.** column is r
28440 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 eturned. If the
28450 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 Nth column of t
28460 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 he result set is
28470 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
28480 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 n or subquery, t
28490 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 hen a NULL point
284a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
284b0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 ** The returned
284c0 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 string is always
284d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 UTF-8 encoded.
284e0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 {END}.**.** For
284f0 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 example, given t
28500 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
28510 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 ma:.**.** CREATE
28520 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 TABLE t1(c1 VAR
28530 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 IANT);.**.** and
28540 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
28550 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
28560 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 ompiled:.**.** S
28570 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 ELECT c1 + 1, c1
28580 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 FROM t1;.**.**
28590 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 this routine wou
285a0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 ld return the st
285b0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 ring "VARIANT" f
285c0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 or the second re
285d0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 sult.** column (
285e0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c i==1), and a NUL
285f0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 L pointer for th
28600 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 e first result c
28610 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a olumn (i==0)..**
28620 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
28630 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 dynamic run-time
28640 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 typing. So jus
28650 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 t because a colu
28660 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 mn.** is declare
28670 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 d to contain a p
28680 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 articular type d
28690 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 oes not mean tha
286a0 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 t the.** data st
286b0 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c ored in that col
286c0 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 umn is of the de
286d0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 clared type. SQ
286e0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e Lite is.** stron
286f0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 gly typed, but t
28700 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e he typing is dyn
28710 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e amic not static.
28720 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 Type.** is ass
28730 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 ociated with ind
28740 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 ividual values,
28750 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e not with the con
28760 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 tainers.** used
28770 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 to hold those va
28780 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 lues..**.** INVA
28790 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
287a0 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 13761} A succes
287b0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
287c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
287d0 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72 65 74 75 ltype(S,N)] retu
287e0 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 rns a.**
287f0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 zero-terminat
28800 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 ed UTF-8 string
28810 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 containing the d
28820 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 eclared datatype
28830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 .** of
28840 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
28850 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 n that appears a
28860 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e s the Nth column
28870 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20 20 (numbered.**
28880 20 20 20 20 20 20 20 20 66 72 6f 6d 20 30 29 20 from 0)
28890 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
288a0 74 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 t to the [prepar
288b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e ed statement] S.
288c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d 20 .**.** {H13762}
288d0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
288e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
288f0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 olumn_decltype16
28900 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 (S,N)].**
28910 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 returns a ze
28920 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
28930 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
28940 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a order string.**
28950 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 conta
28960 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 ining the declar
28970 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 ed datatype of t
28980 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 he table column
28990 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 that appears.**
289a0 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 as the
289b0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d Nth column (num
289c0 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 bered from 0) of
289d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
289e0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 to the.**
289f0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
28a00 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a atement] S..**.*
28a10 2a 20 7b 48 31 33 37 36 33 7d 20 20 49 66 20 4e * {H13763} If N
28a20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20 is less than 0
28a30 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72 20 or N is greater
28a40 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
28a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 .** th
28a60 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
28a70 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 mns in the [prep
28a80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
28a90 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 S,.**
28aa0 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f or if the Nth co
28ab0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 lumn of S is an
28ac0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
28ad0 62 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a bquery rather.**
28ae0 20 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 than
28af0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 a table column,
28b00 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 or if a memory a
28b10 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 llocation failur
28b20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f e.** o
28b30 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 ccurs during enc
28b40 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e oding conversion
28b50 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 s, then.**
28b60 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 calls to [s
28b70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
28b80 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a cltype(S,N)] or.
28b90 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 ** [sq
28ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
28bb0 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 ltype16(S,N)] re
28bc0 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f turn NULL..*/.co
28bd0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
28be0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
28bf0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
28c00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 int);.const void
28c10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
28c20 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 _decltype16(sqli
28c30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
28c40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
28c50 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c Evaluate An SQL
28c60 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 Statement {H132
28c70 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 00} <S10000>.**.
28c80 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 ** After a [prep
28c90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
28ca0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
28cb0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a d using either.*
28cc0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
28cd0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
28ce0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
28cf0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 2()] or one of t
28d00 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
28d10 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
28d20 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b _prepare()] or [
28d30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
28d40 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 6()], this funct
28d50 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 ion.** must be c
28d60 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 alled one or mor
28d70 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 e times to evalu
28d80 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
28d90 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
28da0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 ails of the beha
28db0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 vior of the sqli
28dc0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 te3_step() inter
28dd0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f face depend.** o
28de0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 n whether the st
28df0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 atement was prep
28e00 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e ared using the n
28e10 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 ewer "v2" interf
28e20 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ace.** [sqlite3_
28e30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
28e40 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
28e50 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 re16_v2()] or th
28e60 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a e older legacy.*
28e70 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c * interface [sql
28e80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
28e90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
28ea0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 pare16()]. The
28eb0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 use of the.** ne
28ec0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 w "v2" interface
28ed0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
28ee0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 for new applicat
28ef0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 ions but the leg
28f00 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
28f10 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 will continue t
28f20 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a o be supported..
28f30 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 **.** In the leg
28f40 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
28f50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
28f60 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b will be either [
28f70 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a SQLITE_BUSY],.**
28f80 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
28f90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 [SQLITE_ROW], [S
28fa0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 QLITE_ERROR], or
28fb0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
28fc0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 ..** With the "v
28fd0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 2" interface, an
28fe0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b y of the other [
28ff0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 result codes] or
29000 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
29010 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 sult codes] migh
29020 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 t be returned as
29030 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 well..**.** [SQ
29040 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 LITE_BUSY] means
29050 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
29060 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e se engine was un
29070 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 able to acquire
29080 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
29090 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 locks it needs t
290a0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 o do its job. I
290b0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
290c0 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a is a [COMMIT].**
290d0 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 or occurs outsi
290e0 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 de of an explici
290f0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
29100 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 hen you can retr
29110 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 y the.** stateme
29120 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 nt. If the stat
29130 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b ement is not a [
29140 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 COMMIT] and occu
29150 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 rs within a.** e
29160 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
29170 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f ion then you sho
29180 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 uld rollback the
29190 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 transaction bef
291a0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e ore.** continuin
291b0 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 g..**.** [SQLITE
291c0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 _DONE] means tha
291d0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
291e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 has finished exe
291f0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 cuting.** succes
29200 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 sfully. sqlite3
29210 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
29220 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
29230 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 in on this virtu
29240 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 al.** machine wi
29250 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c thout first call
29260 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
29270 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 et()] to reset t
29280 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 he virtual.** ma
29290 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 chine back to it
292a0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e s initial state.
292b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 .**.** If the SQ
292c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e L statement bein
292d0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 g executed retur
292e0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 ns any data, the
292f0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a n [SQLITE_ROW].*
29300 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 * is returned ea
29310 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f ch time a new ro
29320 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 w of data is rea
29330 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e dy for processin
29340 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c g by the.** call
29350 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d er. The values m
29360 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 ay be accessed u
29370 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e sing the [column
29380 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
29390 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 s]..** sqlite3_s
293a0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 tep() is called
293b0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 again to retriev
293c0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f e the next row o
293d0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 f data..**.** [S
293e0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 QLITE_ERROR] mea
293f0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 ns that a run-ti
29400 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 me error (such a
29410 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a s a constraint.*
29420 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 * violation) has
29430 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 occurred. sqli
29440 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c te3_step() shoul
29450 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 d not be called
29460 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 again on.** the
29470 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 VM. More informa
29480 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e tion may be foun
29490 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
294a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
294b0 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 .** With the leg
294c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 acy interface, a
294d0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
294e0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 rror code (for e
294f0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 xample,.** [SQLI
29500 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b TE_INTERRUPT], [
29510 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 SQLITE_SCHEMA],
29520 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d [SQLITE_CORRUPT]
29530 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a , and so forth).
29540 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e ** can be obtain
29550 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 ed by calling [s
29560 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
29570 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 on the.** [prepa
29580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
29590 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 In the "v2" int
295a0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d erface,.** the m
295b0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
295c0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
295d0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 ned directly by
295e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a sqlite3_step()..
295f0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 **.** [SQLITE_MI
29600 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 SUSE] means that
29610 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e the this routin
29620 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 e was called ina
29630 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a ppropriately..**
29640 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 Perhaps it was
29650 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 called on a [pre
29660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
29670 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 that has.** alr
29680 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 eady been [sqlit
29690 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
296a0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f nalized] or on o
296b0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 ne that had.** p
296c0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
296d0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ed [SQLITE_ERROR
296e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
296f0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 E]. Or it could
29700 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 .** be the case
29710 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 that the same da
29720 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
29730 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 n is being used
29740 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 by two or.** mor
29750 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 e threads at the
29760 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 same moment in
29770 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 time..**.** <b>G
29780 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 oofy Interface A
29790 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 lert:</b> In the
297a0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
297b0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 e, the sqlite3_s
297c0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 tep().** API alw
297d0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 ays returns a ge
297e0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 neric error code
297f0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
29800 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a , following any.
29810 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 ** error other t
29820 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 han [SQLITE_BUSY
29830 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 ] and [SQLITE_MI
29840 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 SUSE]. You must
29850 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
29860 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
29870 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
29880 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 )] in order to f
29890 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a ind one of the.*
298a0 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f * specific [erro
298b0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 r codes] that be
298c0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 tter describes t
298d0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 he error..** We
298e0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 admit that this
298f0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 is a goofy desig
29900 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 n. The problem
29910 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a has been fixed.*
29920 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 * with the "v2"
29930 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 interface. If y
29940 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f ou prepare all o
29950 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 f your SQL state
29960 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 ments.** using e
29970 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
29980 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
29990 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
299a0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 16_v2()] instead
299b0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 .** of the legac
299c0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
299d0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
299e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
299f0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 interfaces,.** t
29a00 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 hen the more spe
29a10 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
29a20 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 es] are returned
29a30 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 directly.** by
29a40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
29a50 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 The use of the
29a60 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 "v2" interface i
29a70 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a s recommended..*
29a80 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
29a90 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30 32 7d 20 .**.** {H13202}
29aa0 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 If the [prepare
29ab0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
29ac0 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 75 s ready to be ru
29ad0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 n, then.**
29ae0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 [sqlite3_st
29af0 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20 ep(S)] advances
29b00 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74 that prepared st
29b10 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a atement until.**
29b20 20 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 6c compl
29b30 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 etion or until i
29b40 74 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 t is ready to re
29b50 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 turn another row
29b60 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
29b70 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 2c result set,
29b80 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 or until an [sq
29b90 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 lite3_interrupt
29ba0 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20 | interrupt].**
29bb0 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 20 72 or a r
29bc0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 un-time error oc
29bd0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 curs..**.** {H15
29be0 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 304} When a cal
29bf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
29c00 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68 ep(S)] causes th
29c10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
29c20 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 ement].**
29c30 20 20 20 20 53 20 74 6f 20 72 75 6e 20 74 6f 20 S to run to
29c40 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20 completion, the
29c50 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
29c60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a [SQLITE_DONE]..
29c70 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 36 7d 20 20 **.** {H15306}
29c80 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b When a call to [
29c90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
29ca0 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 stops because i
29cb0 74 20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a t is ready to.**
29cc0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 retur
29cd0 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 n another row of
29ce0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c the result set,
29cf0 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c it returns [SQL
29d00 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 ITE_ROW]..**.**
29d10 7b 48 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 {H15308} If a c
29d20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
29d30 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 step(S)] encount
29d40 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 ers an.**
29d50 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 [sqlite3_int
29d60 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 errupt | interru
29d70 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d pt] or a run-tim
29d80 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 e error,.**
29d90 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73 it returns
29da0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
29db0 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20 error code that
29dc0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a is not one of.**
29dd0 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 [SQLI
29de0 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f TE_OK], [SQLITE_
29df0 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ROW], or [SQLITE
29e00 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 _DONE]..**.** {H
29e10 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 15310} If an [s
29e20 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
29e30 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 | interrupt] or
29e40 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
29e50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f r.** o
29e60 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63 ccurs during a c
29e70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
29e80 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 step(S)].**
29e90 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65 for a [pre
29ea0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
29eb0 20 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 S created using
29ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65 .** le
29ed0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 gacy interfaces
29ee0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
29ef0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 ()] or.**
29f00 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 [sqlite3_pre
29f10 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 pare16()], then
29f20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 the function ret
29f30 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 urns either.**
29f40 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
29f50 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 _ERROR], [SQLITE
29f60 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 _BUSY], or [SQLI
29f70 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 TE_MISUSE]..*/.i
29f80 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 nt sqlite3_step(
29f90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
29fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
29fb0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d Number of colum
29fc0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 ns in a result s
29fd0 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 et {H13770} <S10
29fe0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 700>.**.** Retur
29ff0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2a000 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 values in the c
2a010 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
2a020 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a e result set..**
2a030 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
2a040 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 31 7d 20 20 **.** {H13771}
2a050 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 After a call to
2a060 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2a070 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b ] that returns [
2a080 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 SQLITE_ROW],.**
2a090 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 the [s
2a0a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2a0b0 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 t(S)] routine wi
2a0c0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 ll return the sa
2a0d0 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 me value.**
2a0e0 20 20 20 20 20 20 61 73 20 74 68 65 20 5b 73 71 as the [sq
2a0f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
2a100 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e nt(S)] function.
2a110 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 32 7d 20 .**.** {H13772}
2a120 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f After [sqlite3_
2a130 73 74 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 step(S)] has ret
2a140 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 urned any value
2a150 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 other than.**
2a160 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
2a170 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b ROW] or before [
2a180 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
2a190 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 has been called
2a1a0 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 on the.**
2a1b0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
2a1c0 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 tatement] for th
2a1d0 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e e first time sin
2a1e0 63 65 20 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 ce it was.**
2a1f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2a200 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
2a210 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ed] or [sqlite3_
2a220 72 65 73 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a reset | reset],.
2a230 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 ** the
2a240 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 [sqlite3_data_c
2a250 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 ount(S)] routine
2a260 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a returns zero..*
2a270 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 /.int sqlite3_da
2a280 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 ta_count(sqlite3
2a290 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2a2a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2a2b0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 Fundamental Data
2a2c0 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c types {H10265} <
2a2d0 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a S10110><S10120>.
2a2e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
2a2f0 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b ITE_TEXT.**.** {
2a300 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 H10266} Every va
2a310 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 lue in SQLite ha
2a320 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 s one of five fu
2a330 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 ndamental dataty
2a340 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a pes:.**.** <ul>.
2a350 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 ** <li> 64-bit s
2a360 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
2a370 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 <li> 64-bit IEE
2a380 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 E floating point
2a390 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 number.** <li>
2a3a0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 string.** <li> B
2a3b0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c LOB.** <li> NULL
2a3c0 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a .** </ul> {END}.
2a3d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
2a3e0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
2a3f0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
2a400 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
2a410 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
2a420 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
2a430 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
2a440 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
2a450 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
2a460 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
2a470 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
2a480 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
2a490 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
2a4a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
2a4b0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
2a4c0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
2a4d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e SQLITE3_TEXT, n
2a4e0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
2a4f0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
2a500 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
2a510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
2a520 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
2a530 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
2a540 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
2a550 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
2a560 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
2a570 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
2a580 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
2a590 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
2a5a0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
2a5b0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
2a5c0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
2a5d0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
2a5e0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
2a5f0 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 ery {H13800} <S1
2a600 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0700>.** KEYWORD
2a610 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 S: {column acces
2a620 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a s functions}.**.
2a630 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2a640 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 s form the "resu
2a650 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e lt set query" in
2a660 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
2a670 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
2a680 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
2a690 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 about a single
2a6a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 column of the cu
2a6b0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 rrent.** result
2a6c0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 row of a query.
2a6d0 20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 In every case t
2a6e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2a6f0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
2a700 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
2a710 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2a720 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
2a730 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
2a740 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
2a750 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
2a760 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
2a770 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
2a780 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
2a790 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
2a7a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2a7b0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2a7c0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
2a7d0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
2a7e0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
2a7f0 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 urned. The left
2a800 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
2a810 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
2a820 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
2a830 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 *.** If the SQL
2a840 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
2a850 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 ot currently poi
2a860 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f nt to a valid ro
2a870 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 w, or if the.**
2a880 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 column index is
2a890 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 out of range, th
2a8a0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 e result is unde
2a8b0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 fined..** These
2a8c0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c routines may onl
2a8d0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e y be called when
2a8e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
2a8f0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
2a900 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2a910 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
2a920 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 E_ROW] and neith
2a930 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 er.** [sqlite3_r
2a940 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c eset()] nor [sql
2a950 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2a960 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 have been calle
2a970 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a d subsequently..
2a980 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 ** If any of the
2a990 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
2a9a0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 called after [sq
2a9b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2a9c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
2a9d0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 nalize()] or aft
2a9e0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 er [sqlite3_step
2a9f0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
2aa00 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 .** something ot
2aa10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
2aa20 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c _ROW], the resul
2aa30 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
2aa40 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 ..** If [sqlite3
2aa50 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c _step()] or [sql
2aa60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
2aa70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2aa80 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c ze()].** are cal
2aa90 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 led from a diffe
2aaa0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c rent thread whil
2aab0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 e any of these r
2aac0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 outines.** are p
2aad0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 ending, then the
2aae0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
2aaf0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
2ab00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2ab10 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 _type() routine
2ab20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b returns the.** [
2ab30 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
2ab40 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
2ab50 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
2ab60 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
2ab70 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
2ab80 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 n. The returned
2ab90 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 value is one of
2aba0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
2abb0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c ],.** [SQLITE_FL
2abc0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 OAT], [SQLITE_TE
2abd0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f XT], [SQLITE_BLO
2abe0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e B], or [SQLITE_N
2abf0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 ULL]. The value
2ac00 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
2ac10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2ac20 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 ype() is only me
2ac30 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 aningful if no t
2ac40 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f ype.** conversio
2ac50 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 ns have occurred
2ac60 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 as described be
2ac70 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 low. After a ty
2ac80 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a pe conversion,.*
2ac90 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 * the value retu
2aca0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
2acb0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
2acc0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 undefined. Fut
2acd0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ure.** versions
2ace0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 of SQLite may ch
2acf0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f ange the behavio
2ad00 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c r of sqlite3_col
2ad10 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f umn_type().** fo
2ad20 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 llowing a type c
2ad30 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
2ad40 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 If the result i
2ad50 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2ad60 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2ad70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2ad80 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2ad90 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2ada0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2adb0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2adc0 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 string..** If th
2add0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 e result is a UT
2ade0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 F-16 string, the
2adf0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2ae00 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 _bytes() convert
2ae10 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 s.** the string
2ae20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 to UTF-8 and the
2ae30 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
2ae40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a mber of bytes..*
2ae50 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 * If the result
2ae60 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
2ae70 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
2ae80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 column_bytes() u
2ae90 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
2aea0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
2aeb0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
2aec0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 e to a UTF-8 str
2aed0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
2aee0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
2aef0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
2af00 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 tring..** The va
2af10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 lue returned doe
2af20 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 s not include th
2af30 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
2af40 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 r at the end.**
2af50 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 of the string.
2af60 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 For clarity: the
2af70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
2af80 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
2af90 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 .** bytes in the
2afa0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 string, not the
2afb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
2afc0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 cters..**.** Str
2afd0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
2afe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2aff0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 text() and sqlit
2b000 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
2b010 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 (),.** even empt
2b020 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 y strings, are a
2b030 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 lways zero termi
2b040 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 nated. The retu
2b050 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d rn.** value from
2b060 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2b070 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 blob() for a zer
2b080 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 o-length BLOB is
2b090 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a an arbitrary.**
2b0a0 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 pointer, possib
2b0b0 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 ly even a NULL p
2b0c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
2b0d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2b0e0 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 _bytes16() routi
2b0f0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
2b100 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2b110 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c bytes().** but l
2b120 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 eaves the result
2b130 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 in UTF-16 in na
2b140 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
2b150 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 instead of UTF-8
2b160 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 ..** The zero te
2b170 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 rminator is not
2b180 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 included in this
2b190 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 count..**.** Th
2b1a0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
2b1b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
2b1c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
2b1d0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
2b1e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2b1f0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 e] object. An u
2b200 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2b210 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a e3_value object.
2b220 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ** may only be u
2b230 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 sed with [sqlite
2b240 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 3_bind_value()]
2b250 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 and [sqlite3_res
2b260 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ult_value()]..**
2b270 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 If the [unprote
2b280 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2b290 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 ue] object retur
2b2a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
2b2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2b2c0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e )] is used in an
2b2d0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 y other way, inc
2b2e0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 luding calls.**
2b2f0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 to routines like
2b300 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2b310 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 int()], [sqlite3
2b320 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a _value_text()],.
2b330 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 ** or [sqlite3_v
2b340 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 alue_bytes()], t
2b350 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
2b360 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2b370 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
2b380 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 nes attempt to c
2b390 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 onvert the value
2b3a0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 where appropria
2b3b0 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d te. For.** exam
2b3c0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 ple, if the inte
2b3d0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
2b3e0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 ion is FLOAT and
2b3f0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a a text result.*
2b400 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 * is requested,
2b410 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
2b420 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 f()] is used int
2b430 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f ernally to perfo
2b440 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 rm the.** conver
2b450 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c sion automatical
2b460 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 ly. The followi
2b470 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 ng table details
2b480 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 the conversions
2b490 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 .** that are app
2b4a0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lied:.**.** <blo
2b4b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
2b4c0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
2b4d0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 * <tr><th> Inter
2b4e0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e nal<br>Type <th>
2b4f0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 Requested<br>Ty
2b500 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 pe <th> Convers
2b510 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 ion.**.** <tr><t
2b520 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
2b530 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2b540 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c Result is 0.** <
2b550 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2b560 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
2b570 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
2b580 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 .0.** <tr><td>
2b590 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 NULL <td> T
2b5a0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 EXT <td> Resu
2b5b0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 lt is NULL point
2b5c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
2b5d0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 NULL <td> B
2b5e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 LOB <td> Resu
2b5f0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 lt is NULL point
2b600 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 er.** <tr><td> I
2b610 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c NTEGER <td> FL
2b620 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 OAT <td> Conv
2b630 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 ert from integer
2b640 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 to float.** <tr
2b650 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
2b660 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
2b670 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 d> ASCII renderi
2b680 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 ng of the intege
2b690 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
2b6a0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c TEGER <td> BL
2b6b0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 OB <td> Same
2b6c0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 as INTEGER->TEXT
2b6d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
2b6e0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OAT <td> INTEG
2b6f0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 ER <td> Conver
2b700 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 t from float to
2b710 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
2b720 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2b730 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2b740 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
2b750 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a of the float.**
2b760 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2b770 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2b780 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 <td> Same as F
2b790 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 LOAT->TEXT.** <t
2b7a0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2b7b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
2b7c0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a td> Use atoi().*
2b7d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2b7e0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
2b7f0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 <td> Use atof
2b800 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
2b810 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 TEXT <td> B
2b820 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 LOB <td> No c
2b830 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 hange.** <tr><td
2b840 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
2b850 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 INTEGER <td> C
2b860 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 onvert to TEXT t
2b870 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a hen use atoi().*
2b880 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2b890 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
2b8a0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2b8b0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
2b8c0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c atof().** <tr><
2b8d0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
2b8e0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2b8f0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d Add a zero term
2b900 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 inator if needed
2b910 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 .** </table>.**
2b920 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
2b930 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 .** The table ab
2b940 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 ove makes refere
2b950 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 nce to standard
2b960 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 C library functi
2b970 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e ons atoi().** an
2b980 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 d atof(). SQLit
2b990 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c e does not reall
2b9a0 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 y use these func
2b9b0 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 tions. It has i
2b9c0 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 ts.** own equiva
2b9d0 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f lent internal ro
2b9e0 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f utines. The ato
2b9f0 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e i() and atof() n
2ba00 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 ames are.** used
2ba10 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f in the table fo
2ba20 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 r brevity and be
2ba30 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 cause they are f
2ba40 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a amiliar to most.
2ba50 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 ** C programmers
2ba60 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
2ba70 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 t when type conv
2ba80 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 ersions occur, p
2ba90 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
2baa0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c by prior.** cal
2bab0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
2bac0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c lumn_blob(), sql
2bad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2bae0 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 (), and/or.** sq
2baf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2bb00 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 t16() may be inv
2bb10 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 alidated..** Typ
2bb20 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e e conversions an
2bb30 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 d pointer invali
2bb40 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 dations might oc
2bb50 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f cur.** in the fo
2bb60 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a llowing cases:.*
2bb70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2bb80 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
2bb90 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 ntent is a BLOB
2bba0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
2bbb0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 mn_text() or.**
2bbc0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
2bbd0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 umn_text16() is
2bbe0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d called. A zero-
2bbf0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 terminator might
2bc00 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f .** need to
2bc10 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 be added to the
2bc20 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a string.</li>.**
2bc30 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
2bc40 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 l content is UTF
2bc50 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 -8 text and sqli
2bc60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2bc70 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 16() or.**
2bc80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2bc90 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
2bca0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
2bcb0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
2bcc0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 d.** to UTF
2bcd0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 -16.</li>.** <li
2bce0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
2bcf0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 ntent is UTF-16
2bd00 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
2bd10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2bd20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
2bd30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2bd40 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
2bd50 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
2bd60 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
2bd70 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 to UTF-8.</li
2bd80 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a >.** </ul>.**.**
2bd90 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 Conversions bet
2bda0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e ween UTF-16be an
2bdb0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 d UTF-16le are a
2bdc0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c lways done in pl
2bdd0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f ace and do.** no
2bde0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 t invalidate a p
2bdf0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 rior pointer, th
2be00 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 ough of course t
2be10 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
2be20 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 e buffer.** that
2be30 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 the prior point
2be40 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c er points to wil
2be50 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 l have been modi
2be60 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e fied. Other kin
2be70 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 ds.** of convers
2be80 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 ion are done in
2be90 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 place when it is
2bea0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 possible, but s
2beb0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a ometimes they.**
2bec0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c are not possibl
2bed0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 e and in those c
2bee0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 ases prior point
2bef0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 ers are invalida
2bf00 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ted..**.** The s
2bf10 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 afest and easies
2bf20 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f t to remember po
2bf30 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b licy is to invok
2bf40 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
2bf50 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 .** in one of th
2bf60 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 e following ways
2bf70 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
2bf80 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
2bf90 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f umn_text() follo
2bfa0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
2bfb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
2bfc0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
2bfd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
2bfe0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
2bff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2c000 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
2c010 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2c020 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 text16() followe
2c030 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2c040 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c umn_bytes16()</l
2c050 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
2c060 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
2c070 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c , you should cal
2c080 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e l sqlite3_column
2c090 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 _text(),.** sqli
2c0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2c0b0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f ), or sqlite3_co
2c0c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 lumn_text16() fi
2c0d0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 rst to force the
2c0e0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 result.** into
2c0f0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d the desired form
2c100 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 at, then invoke
2c110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c120 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c ytes() or.** sql
2c130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2c140 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 s16() to find th
2c150 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 e size of the re
2c160 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 sult. Do not mi
2c170 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 x calls.** to sq
2c180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2c190 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 t() or sqlite3_c
2c1a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 olumn_blob() wit
2c1b0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 h calls to.** sq
2c1c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2c1d0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e es16(), and do n
2c1e0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 ot mix calls to
2c1f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2c200 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 ext16().** with
2c210 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2c220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e _column_bytes().
2c230 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 .**.** The point
2c240 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 ers returned are
2c250 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 valid until a t
2c260 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f ype conversion o
2c270 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 ccurs as.** desc
2c280 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 ribed above, or
2c290 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 until [sqlite3_s
2c2a0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 tep()] or [sqlit
2c2b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2c2c0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2c2d0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ize()] is called
2c2e0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 . The memory sp
2c2f0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 ace used to hold
2c300 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 strings.** and
2c310 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 BLOBs is freed a
2c320 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 utomatically. D
2c330 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 o <b>not</b> pas
2c340 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 s the pointers r
2c350 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 eturned.** [sqli
2c360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2c370 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c )], [sqlite3_col
2c380 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 umn_text()], etc
2c390 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 . into.** [sqlit
2c3a0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a e3_free()]..**.*
2c3b0 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c * If a memory al
2c3c0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f location error o
2c3d0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 ccurs during the
2c3e0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 evaluation of a
2c3f0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 ny.** of these r
2c400 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 outines, a defau
2c410 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 lt value is retu
2c420 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 rned. The defau
2c430 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 lt value.** is e
2c440 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 ither the intege
2c450 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e r 0, the floatin
2c460 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 g point number 0
2c470 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a .0, or a NULL.**
2c480 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 pointer. Subse
2c490 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
2c4a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
2c4b0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a )] will return.*
2c4c0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
2c4d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
2c4e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 TS:.**.** {H1380
2c4f0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
2c500 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 column_blob(S,N)
2c510 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
2c520 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
2c530 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 Nth column
2c540 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
2c550 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
2c560 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 set for.**
2c570 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 the [prepar
2c580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2c590 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 into a BLOB and
2c5a0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a then returns a.*
2c5b0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 * point
2c5c0 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 er to the conver
2c5d0 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a ted value..**.**
2c5e0 20 7b 48 31 33 38 30 36 7d 20 54 68 65 20 5b 73 {H13806} The [s
2c5f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2c600 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 tes(S,N)] interf
2c610 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a ace returns the.
2c620 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 ** numb
2c630 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2c640 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e he BLOB or strin
2c650 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 g (exclusive of
2c660 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2c670 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
2c680 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 on the string) t
2c690 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 hat was returned
2c6a0 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 by the.**
2c6b0 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 most recent
2c6c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2c6d0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e _column_blob(S,N
2c6e0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 )] or.**
2c6f0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d [sqlite3_colum
2c700 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a n_text(S,N)]..**
2c710 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20 54 68 65 .** {H13809} The
2c720 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c730 5f 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 _bytes16(S,N)] i
2c740 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2c750 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2c760 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2c770 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 in the string (
2c780 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 exclusive of the
2c790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
2c7a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 o terminator on
2c7b0 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 the string) that
2c7c0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 was returned by
2c7d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2c7e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
2c7f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
2c800 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 lumn_text16(S,N)
2c810 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 ]..**.** {H13812
2c820 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2c830 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e olumn_double(S,N
2c840 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
2c850 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
2c860 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e Nth column
2c870 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
2c880 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2c890 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a t set for the.**
2c8a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
2c8b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2c8c0 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 into a floating
2c8d0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 point value and
2c8e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
2c8f0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 urns a copy of t
2c900 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a hat value..**.**
2c910 20 7b 48 31 33 38 31 35 7d 20 54 68 65 20 5b 73 {H13815} The [s
2c920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
2c930 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 t(S,N)] interfac
2c940 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a e converts the.*
2c950 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 * Nth c
2c960 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
2c970 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
2c980 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 result set for t
2c990 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
2c9a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c9b0 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d nt] S into a 64-
2c9c0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
2c9d0 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 er and.**
2c9e0 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c returns the l
2c9f0 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 ower 32 bits of
2ca00 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a that integer..**
2ca10 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20 54 68 65 .** {H13818} The
2ca20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2ca30 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 _int64(S,N)] int
2ca40 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
2ca50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2ca60 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 Nth column in th
2ca70 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 e current row of
2ca80 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
2ca90 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 for the.**
2caa0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
2cab0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 atement] S into
2cac0 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 a 64-bit signed
2cad0 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 integer and.**
2cae0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 returns
2caf0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 a copy of that i
2cb00 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 nteger..**.** {H
2cb10 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 13821} The [sqli
2cb20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2cb30 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2cb40 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2cb50 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c Nth col
2cb60 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 umn in the curre
2cb70 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2cb80 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 sult set for.**
2cb90 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 the [pr
2cba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2cbb0 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d ] S into a zero-
2cbc0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
2cbd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 .** str
2cbe0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ing and returns
2cbf0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
2cc00 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 t string..**.**
2cc10 7b 48 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 {H13824} The [sq
2cc20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2cc30 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 t16(S,N)] interf
2cc40 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
2cc50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
2cc60 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 column in the c
2cc70 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
2cc80 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 e result set for
2cc90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2cca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2ccb0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a ment] S into a z
2ccc0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 ero-terminated 2
2ccd0 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 -byte.**
2cce0 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 aligned UTF-16
2ccf0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
2cd00 65 72 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 er string and re
2cd10 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 turns.**
2cd20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 a pointer to t
2cd30 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a hat string..**.*
2cd40 2a 20 7b 48 31 33 38 32 37 7d 20 54 68 65 20 5b * {H13827} The [
2cd50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2cd60 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 ype(S,N)] interf
2cd70 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 ace returns.**
2cd80 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b one of [
2cd90 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 SQLITE_NULL], [S
2cda0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 QLITE_INTEGER],
2cdb0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a [SQLITE_FLOAT],.
2cdc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
2cdd0 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 ITE_TEXT], or [S
2cde0 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 QLITE_BLOB] as a
2cdf0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a ppropriate for.*
2ce00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 4e * the N
2ce10 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
2ce20 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
2ce30 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
2ce40 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
2ce50 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2ce60 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a tement] S..**.**
2ce70 20 7b 48 31 33 38 33 30 7d 20 54 68 65 20 5b 73 {H13830} The [s
2ce80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2ce90 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 lue(S,N)] interf
2cea0 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a ace returns a.**
2ceb0 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 pointe
2cec0 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 r to an [unprote
2ced0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2cee0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 ue] object for t
2cef0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
2cf00 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
2cf10 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
2cf20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
2cf30 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
2cf40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2cf50 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f tement] S..*/.co
2cf60 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2cf70 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 3_column_blob(sq
2cf80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2cf90 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
2cfa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2cfb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2cfc0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 int iCol);.int s
2cfd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2cfe0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 tes16(sqlite3_st
2cff0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2d000 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 double sqlite3_c
2d010 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c olumn_double(sql
2d020 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2d030 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
2d040 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 e3_column_int(sq
2d050 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d060 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f iCol);.sqlite3_
2d070 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f int64 sqlite3_co
2d080 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 lumn_int64(sqlit
2d090 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2d0a0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 ol);.const unsig
2d0b0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ned char *sqlite
2d0c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 3_column_text(sq
2d0d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d0e0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f iCol);.const vo
2d0f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
2d100 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 mn_text16(sqlite
2d110 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2d120 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2d130 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 column_type(sqli
2d140 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
2d150 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 Col);.sqlite3_va
2d160 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c lue *sqlite3_col
2d170 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 umn_value(sqlite
2d180 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2d190 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
2d1a0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 REF: Destroy A P
2d1b0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2d1c0 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 t Object {H13300
2d1d0 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 } <S70300><S3010
2d1e0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
2d1f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
2d200 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
2d210 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b ed to delete a [
2d220 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d230 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 nt]..** If the s
2d240 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 tatement was exe
2d250 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c cuted successful
2d260 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 ly or not execut
2d270 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a ed at all, then.
2d280 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 ** SQLITE_OK is
2d290 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 returned. If exe
2d2a0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 cution of the st
2d2b0 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 atement failed t
2d2c0 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 hen an.** [error
2d2d0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e code] or [exten
2d2e0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ded error code]
2d2f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2d300 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
2d310 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 can be called at
2d320 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e any point durin
2d330 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 g the execution
2d340 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 of the.** [prepa
2d350 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
2d360 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 If the virtual
2d370 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a machine has not.
2d380 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 ** completed exe
2d390 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 cution when this
2d3a0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
2d3b0 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 ed, that is like
2d3c0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 .** encountering
2d3d0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 an error or an
2d3e0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
2d3f0 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e pt | interrupt].
2d400 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 .** Incomplete u
2d410 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f pdates may be ro
2d420 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 lled back and tr
2d430 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 ansactions cance
2d440 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e led,.** dependin
2d450 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 g on the circums
2d460 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a tances, and the.
2d470 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
2d480 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 returned will be
2d490 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e [SQLITE_ABORT].
2d4a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
2d4b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 S:.**.** {H11302
2d4c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 } The [sqlite3_f
2d4d0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 inalize(S)] inte
2d4e0 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 74 rface destroys t
2d4f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
2d500 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d510 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73 nt] S and releas
2d520 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 es all.**
2d530 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69 memory and fi
2d540 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c le resources hel
2d550 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74 d by that object
2d560 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34 7d ..**.** {H11304}
2d570 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 If the most rec
2d580 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
2d590 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
2d5a0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 r the.**
2d5b0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
2d5c0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 ement] S returne
2d5d0 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 d an error,.**
2d5e0 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 then [sq
2d5f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
2d600 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 )] returns that
2d610 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 same error..*/.i
2d620 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c nt sqlite3_final
2d630 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ize(sqlite3_stmt
2d640 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2d650 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
2d660 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
2d670 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 ement Object {H1
2d680 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3330} <S70300>.*
2d690 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2d6a0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f _reset() functio
2d6b0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 n is called to r
2d6c0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 eset a [prepared
2d6d0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
2d6e0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 bject back to it
2d6f0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c s initial state,
2d700 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d ready to be re-
2d710 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 executed..** Any
2d720 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
2d730 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
2d740 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
2d750 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
2d760 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2d770 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
2d780 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
2d790 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
2d7a0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
2d7b0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2d7c0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
2d7d0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
2d7e0 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 ** {H11332} The
2d7f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2d800 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
2d810 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ets the [prepare
2d820 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a d statement] S.*
2d830 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 * back
2d840 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
2d850 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e of its program.
2d860 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 .**.** {H11334}
2d870 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
2d880 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
2d890 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
2d8a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2d8b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2d8c0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 ment] S returned
2d8d0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 [SQLITE_ROW] or
2d8e0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a [SQLITE_DONE],.
2d8f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 ** or i
2d900 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
2d910 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 S)] has never be
2d920 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 fore been called
2d930 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 on S,.**
2d940 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 then [sqlite3
2d950 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
2d960 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
2d970 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 **.** {H11336} I
2d980 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
2d990 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
2d9a0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
2d9b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2d9c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2d9d0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 ent] S indicated
2d9e0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a an error, then.
2d9f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
2da00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
2da10 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
2da20 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
2da30 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 e]..**.** {H1133
2da40 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 8} The [sqlite3_
2da50 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
2da60 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 ace does not cha
2da70 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a nge the values.*
2da80 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e * of an
2da90 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
2daa0 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
2dab0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
2dac0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
2dad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 .int sqlite3_res
2dae0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
2daf0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2db00 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
2db10 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
2db20 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 Functions {H161
2db30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 00} <S20200>.**
2db40 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 KEYWORDS: {funct
2db50 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 ion creation rou
2db60 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 tines}.** KEYWOR
2db70 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
2db80 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2db90 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 ction}.** KEYWOR
2dba0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
2dbb0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2dbc0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 ctions}.**.** Th
2dbd0 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ese two function
2dbe0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 s (collectively
2dbf0 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 known as "functi
2dc00 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
2dc10 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 ines").** are us
2dc20 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 ed to add SQL fu
2dc30 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
2dc40 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 gates or to rede
2dc50 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
2dc60 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 r.** of existing
2dc70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f SQL functions o
2dc80 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 r aggregates. T
2dc90 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e he only differen
2dca0 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a ce between the.*
2dcb0 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 * two is that th
2dcc0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
2dcd0 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 er, the name of
2dce0 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e the (scalar) fun
2dcf0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
2dd00 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 egate, is encode
2dd10 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 d in UTF-8 for s
2dd20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2dd30 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 nction() and UTF
2dd40 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 -16.** for sqlit
2dd50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2dd60 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 on16()..**.** Th
2dd70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2dd80 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
2dd90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
2dda0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
2ddb0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
2ddc0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 o be added. If
2ddd0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d a single program
2dde0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
2ddf0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 one database.**
2de00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 connection inter
2de10 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 nally, then SQL
2de20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
2de30 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 e added individu
2de40 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 ally to.** each
2de50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2de60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
2de70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
2de80 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
2de90 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
2dea0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 to be created or
2deb0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 .** redefined.
2dec0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 The length of th
2ded0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 e name is limite
2dee0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 d to 255 bytes,
2def0 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 exclusive of.**
2df00 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
2df10 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 tor. Note that
2df20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 the name length
2df30 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 limit is in byte
2df40 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 s, not.** charac
2df50 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d ters. Any attem
2df60 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
2df70 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
2df80 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
2df90 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
2dfa0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e LITE_ERROR] bein
2dfb0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a g returned..**.*
2dfc0 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 * The third para
2dfd0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
2dfe0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
2dff0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
2e000 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2e010 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
2e020 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 takes. If this
2e030 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 parameter is neg
2e040 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
2e050 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
2e060 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 ** aggregate may
2e070 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 take any number
2e080 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a of arguments..*
2e090 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 *.** The fourth
2e0a0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 parameter, eText
2e0b0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 Rep, specifies w
2e0c0 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 hat.** [SQLITE_U
2e0d0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 TF8 | text encod
2e0e0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 ing] this SQL fu
2e0f0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 nction prefers f
2e100 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 or.** its parame
2e110 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 ters. Any SQL f
2e120 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2e130 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 tation should be
2e140 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a able to work.**
2e150 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 work with UTF-8
2e160 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 , UTF-16le, or U
2e170 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f TF-16be. But so
2e180 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f me implementatio
2e190 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 ns may be.** mor
2e1a0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 e efficient with
2e1b0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 one encoding th
2e1c0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 an another. It
2e1d0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a is allowed to.**
2e1e0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
2e1f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2e200 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 ) or sqlite3_cre
2e210 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
2e220 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d multiple.** tim
2e230 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 es with the same
2e240 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 function but wi
2e250 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c th different val
2e260 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e ues of eTextRep.
2e270 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c .** When multipl
2e280 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2e290 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
2e2a0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
2e2b0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
2e2c0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
2e2d0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
2e2e0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
2e2f0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
2e300 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 ion..** If there
2e310 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c is only a singl
2e320 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2e330 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 which does not
2e340 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a care what text.*
2e350 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 * encoding is us
2e360 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 ed, then the fou
2e370 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rth argument sho
2e380 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 uld be [SQLITE_A
2e390 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 NY]..**.** The f
2e3a0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 ifth parameter i
2e3b0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 s an arbitrary p
2e3c0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 ointer. The imp
2e3d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
2e3e0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 he.** function c
2e3f0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 an gain access t
2e400 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 o this pointer u
2e410 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 sing [sqlite3_us
2e420 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a er_data()]..**.*
2e430 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 * The seventh, e
2e440 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 ighth and ninth
2e450 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e parameters, xFun
2e460 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 c, xStep and xFi
2e470 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e nal, are.** poin
2e480 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 ters to C-langua
2e490 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ge functions tha
2e4a0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
2e4b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
2e4c0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 ** aggregate. A
2e4d0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
2e4e0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
2e4f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2e500 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 f the xFunc.** c
2e510 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 allback only, NU
2e520 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 LL pointers shou
2e530 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 ld be passed as
2e540 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 the xStep and xF
2e550 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 inal.** paramete
2e560 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 rs. An aggregate
2e570 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
2e580 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
2e590 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 entation of xSte
2e5a0 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 p.** and xFinal
2e5b0 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 and NULL should
2e5c0 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 be passed for xF
2e5d0 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 unc. To delete a
2e5e0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 n existing.** SQ
2e5f0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
2e600 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 gregate, pass NU
2e610 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 LL for all three
2e620 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 function callba
2e630 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 cks..**.** It is
2e640 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 permitted to re
2e650 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 gister multiple
2e660 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
2e670 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 of the same.** f
2e680 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 unctions with th
2e690 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 e same name but
2e6a0 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 with either diff
2e6b0 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 ering numbers of
2e6c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 .** arguments or
2e6d0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 differing prefe
2e6e0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
2e6f0 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c ngs. SQLite wil
2e700 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 l use.** the imp
2e710 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 lementation most
2e720 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
2e730 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
2e740 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
2e750 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
2e760 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 A function imple
2e770 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 mentation with a
2e780 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a non-negative.**
2e790 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 nArg parameter
2e7a0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 is a better matc
2e7b0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
2e7c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
2e7d0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 with.** a negat
2e7e0 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e ive nArg. A fun
2e7f0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
2e800 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
2e810 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 ncoding.** match
2e820 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
2e830 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 encoding is a be
2e840 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 tter.** match th
2e850 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
2e860 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
2e870 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 is different.
2e880 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 .** A function w
2e890 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
2e8a0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 g difference is
2e8b0 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 between UTF16le
2e8c0 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 and UTF16be.** i
2e8d0 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 s a closer match
2e8e0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
2e8f0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
2e900 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
2e910 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 s.** between UTF
2e920 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 8 and UTF16..**.
2e930 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 ** Built-in func
2e940 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 tions may be ove
2e950 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 rloaded by new a
2e960 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2e970 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ed functions..**
2e980 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 The first appli
2e990 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2e9a0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 unction with a g
2e9b0 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 iven name overri
2e9c0 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 des all.** built
2e9d0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e -in functions in
2e9e0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
2e9f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2ea00 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
2ea10 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e me..** Subsequen
2ea20 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 t application-de
2ea30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 fined functions
2ea40 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 of the same name
2ea50 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a only override .
2ea60 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 ** prior applica
2ea70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2ea80 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 ctions that are
2ea90 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 an exact match f
2eaa0 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 or the.** number
2eab0 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 of parameters a
2eac0 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 nd preferred enc
2ead0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 oding..**.** An
2eae0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2eaf0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
2eb00 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c permitted to cal
2eb10 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 l other.** SQLit
2eb20 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 e interfaces. H
2eb30 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c owever, such cal
2eb40 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 ls must not.** c
2eb50 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
2eb60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 e connection nor
2eb70 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 finalize or res
2eb80 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a et the prepared.
2eb90 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 ** statement in
2eba0 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 which the functi
2ebb0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
2ebc0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
2ebd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 .**.** {H16103}
2ebe0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 The [sqlite3_cre
2ebf0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 ate_function16(D
2ec00 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 ,X,...)] interfa
2ec10 63 65 20 73 68 61 6c 6c 20 62 65 68 61 76 65 0a ce shall behave.
2ec20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b ** as [
2ec30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2ec40 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 unction(D,X,...)
2ec50 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 ] in every way e
2ec60 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a xcept that it.**
2ec70 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 interp
2ec80 72 65 74 73 20 74 68 65 20 58 20 61 72 67 75 6d rets the X argum
2ec90 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d ent as zero-term
2eca0 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a inated UTF-16.**
2ecb0 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65 native
2ecc0 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 byte order inst
2ecd0 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 ead of as zero-t
2ece0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e erminated UTF-8.
2ecf0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20 .**.** {H16106}
2ed00 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 A successful inv
2ed10 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a ocation of the.*
2ed20 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
2ed30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2ed40 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 ion(D,X,N,E,...)
2ed50 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
2ed60 6c 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20 20 l register.**
2ed70 20 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 or replac
2ed80 65 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 es callback func
2ed90 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 tions in the [da
2eda0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2edb0 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 n] D.**
2edc0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
2edd0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
2ede0 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 ion named X with
2edf0 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a N parameters.**
2ee00 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 and ha
2ee10 76 69 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 ving a preferred
2ee20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f text encoding o
2ee30 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 f E..**.** {H161
2ee40 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 09} A successful
2ee50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2ee60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2ee70 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c n(D,X,N,E,P,F,S,
2ee80 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 L)].**
2ee90 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 20 74 68 shall replace th
2eea0 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c e P, F, S, and L
2eeb0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 values from any
2eec0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 prior calls wit
2eed0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 h.** th
2eee0 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 e same D, X, N,
2eef0 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a and E values..**
2ef00 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54 68 65 .** {H16112} The
2ef10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2ef20 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e _function(D,X,..
2ef30 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 .)] interface sh
2ef40 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 all fail.**
2ef50 20 20 20 20 20 69 66 20 74 68 65 20 53 51 4c 20 if the SQL
2ef60 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 function name X
2ef70 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c is.** l
2ef80 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 onger than 255 b
2ef90 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f ytes exclusive o
2efa0 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 f the zero termi
2efb0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nator..**.** {H1
2efc0 36 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 6118} The [sqlit
2efd0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2efe0 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 on(D,X,N,E,P,F,S
2eff0 2c 4c 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a ,L)] interface.*
2f000 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
2f010 20 66 61 69 6c 20 75 6e 6c 65 73 73 20 65 69 74 fail unless eit
2f020 68 65 72 20 46 20 69 73 20 4e 55 4c 4c 20 61 6e her F is NULL an
2f030 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f d S and L are no
2f040 6e 2d 4e 55 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 n-NULL or.***
2f050 20 20 20 20 20 20 46 20 69 73 20 6e 6f 6e 2d 4e F is non-N
2f060 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 ULL and S and L
2f070 61 72 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 are NULL..**.**
2f080 7b 48 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 {H16121} The [sq
2f090 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f0a0 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e ction(D,...)] in
2f0b0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 terface shall fa
2f0c0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 ils with an.**
2f0d0 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f error co
2f0e0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 de of [SQLITE_BU
2f0f0 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 SY] if there exi
2f100 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 st [prepared sta
2f110 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 tements].**
2f120 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 associated
2f130 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
2f140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
2f150 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d ..**.** {H16124}
2f160 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 The [sqlite3_cr
2f170 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2f180 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 X,N,...)] interf
2f190 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 ace shall fail w
2f1a0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ith.**
2f1b0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 an error code of
2f1c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2f1d0 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 if parameter N i
2f1e0 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 s less.**
2f1f0 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 than -1 or gr
2f200 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a eater than 127..
2f210 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 **.** {H16127} W
2f220 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 hen N is non-neg
2f230 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 ative, the [sqli
2f240 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2f250 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a ion(D,X,N,...)].
2f260 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
2f270 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 rface shall regi
2f280 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 ster callbacks t
2f290 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 o be invoked for
2f2a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2f2b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a SQL function.**
2f2c0 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 named
2f2d0 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 X when the numbe
2f2e0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
2f2f0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 o the SQL functi
2f300 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 on is.**
2f310 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a exactly N..**.
2f320 2a 2a 20 7b 48 31 36 31 33 30 7d 20 57 68 65 6e ** {H16130} When
2f330 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 N is -1, the [s
2f340 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2f350 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e nction(D,X,N,...
2f360 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 )].** i
2f370 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 nterface shall r
2f380 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
2f390 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 s to be invoked
2f3a0 66 6f 72 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 for the SQL.**
2f3b0 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e function
2f3c0 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e named X with an
2f3d0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 y number of argu
2f3e0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ments..**.** {H1
2f3f0 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 6133} When calls
2f400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
2f410 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 ate_function(D,X
2f420 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,N,...)].**
2f430 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c specify mul
2f440 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2f450 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2f460 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 e function X.**
2f470 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 and whe
2f480 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 n one implementa
2f490 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e tion has N>=0 an
2f4a0 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 d the other has
2f4b0 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 N=(-1).**
2f4c0 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 the implement
2f4d0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e ation with a non
2f4e0 2d 7a 65 72 6f 20 4e 20 73 68 61 6c 6c 20 62 65 -zero N shall be
2f4f0 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a preferred..**.*
2f500 2a 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 * {H16136} When
2f510 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
2f520 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2f530 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a n(D,X,N,E,...)].
2f540 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 ** spec
2f550 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ify multiple imp
2f560 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
2f570 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
2f580 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 n X with.**
2f590 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 the same nu
2f5a0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
2f5b0 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 s N but with dif
2f5c0 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 ferent.**
2f5d0 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 encodings E,
2f5e0 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 then the impleme
2f5f0 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 ntation where E
2f600 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 matches the.**
2f610 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 database
2f620 20 65 6e 63 6f 64 69 6e 67 20 73 68 61 6c 6c 20 encoding shall
2f630 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a preferred..**.**
2f640 20 7b 48 31 36 31 33 39 7d 20 46 6f 72 20 61 6e {H16139} For an
2f650 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
2f660 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20 unction created
2f670 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 using.**
2f680 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 [sqlite3_creat
2f690 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e e_function(D,X,N
2f6a0 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 ,E,P,0,S,L)] the
2f6b0 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 finalizer.**
2f6c0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 function
2f6d0 4c 20 73 68 61 6c 6c 20 61 6c 77 61 79 73 20 62 L shall always b
2f6e0 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c e invoked exactl
2f6f0 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a y once if the.**
2f700 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66 step f
2f710 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c unction S is cal
2f720 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 led one or more
2f730 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 times..**.** {H1
2f740 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 6142} When SQLit
2f750 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 e invokes either
2f760 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 the xFunc or xS
2f770 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a tep function of.
2f780 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 ** an a
2f790 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2f7a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
2f7b0 6f 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65 or aggregate cre
2f7c0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ated.**
2f7d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 by [sqlite3_cre
2f7e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
2f7f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 or [sqlite3_crea
2f800 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
2f810 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
2f820 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 en the array of
2f830 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
2f840 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 objects passed a
2f850 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2f860 20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 third paramete
2f870 72 20 73 68 61 6c 6c 20 62 65 20 5b 70 72 6f 74 r shall be [prot
2f880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2f890 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f lue] objects..*/
2f8a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
2f8b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 ate_function(.
2f8c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
2f8d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
2f8e0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
2f8f0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
2f900 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
2f910 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
2f920 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
2f930 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2f940 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2f950 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
2f960 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2f970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2f980 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
2f990 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
2f9a0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 xt*).);.int sqli
2f9b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2f9c0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ion16(. sqlite3
2f9d0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f *db,. const vo
2f9e0 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d id *zFunctionNam
2f9f0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
2fa00 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
2fa10 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
2fa20 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
2fa30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
2fa40 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
2fa50 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
2fa60 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
2fa70 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2fa80 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2fa90 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
2faa0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
2fab0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2fac0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 : Text Encodings
2fad0 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 {H10267} <S5020
2fae0 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 0> <H16100>.**.*
2faf0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
2fb00 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 define integer
2fb10 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 codes that repre
2fb20 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 sent the various
2fb30 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e .** text encodin
2fb40 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 gs supported by
2fb50 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 SQLite..*/.#defi
2fb60 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 ne SQLITE_UTF8
2fb70 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
2fb80 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c ne SQLITE_UTF16L
2fb90 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 E 2.#defi
2fba0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 ne SQLITE_UTF16B
2fbb0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 E 3.#defi
2fbc0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 ne SQLITE_UTF16
2fbd0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 4 /*
2fbe0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 Use native byte
2fbf0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e order */.#defin
2fc00 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 e SQLITE_ANY
2fc10 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 5 /*
2fc20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2fc30 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a unction only */.
2fc40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
2fc50 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 TF16_ALIGNED 8
2fc60 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
2fc70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f eate_collation o
2fc80 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 nly */../*.** CA
2fc90 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
2fca0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ed Functions.**
2fcb0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
2fcc0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
2fcd0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 are [deprecated
2fce0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 ]. In order to
2fcf0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b maintain.** back
2fd00 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
2fd10 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 ity with older c
2fd20 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 ode, these funct
2fd30 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a ions continue .*
2fd40 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 * to be supporte
2fd50 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 d. However, new
2fd60 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 applications sh
2fd70 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 ould avoid.** th
2fd80 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 e use of these f
2fd90 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 unctions. To he
2fda0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f lp encourage peo
2fdb0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 ple to avoid.**
2fdc0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 using these func
2fdd0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f tions, we are no
2fde0 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 t going to tell
2fdf0 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f you what they do
2fe00 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
2fe10 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 ITE_OMIT_DEPRECA
2fe20 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 TED.SQLITE_DEPRE
2fe30 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
2fe40 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
2fe50 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
2fe60 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
2fe70 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
2fe80 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 e3_expired(sqlit
2fe90 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
2fea0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
2feb0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
2fec0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
2fed0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
2fee0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
2fef0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
2ff00 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 sqlite3_global_r
2ff10 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 ecover(void);.SQ
2ff20 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
2ff30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 void sqlite3_thr
2ff40 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 ead_cleanup(void
2ff50 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
2ff60 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
2ff70 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
2ff80 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
2ff90 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 te3_int64,int),v
2ffa0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
2ffb0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
2ffc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
2ffd0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
2ffe0 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
2fff0 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 lues {H15100} <S
30000 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
30010 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
30020 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
30030 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
30040 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
30050 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
30060 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
30070 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
30080 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
30090 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
300a0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
300b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e ..**.** The xFun
300c0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 c (for scalar fu
300d0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 nctions) or xSte
300e0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 p (for aggregate
300f0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a s) parameters.**
30100 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
30110 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
30120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
30130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
30140 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c ].** define call
30150 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 backs that imple
30160 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
30170 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
30180 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 gates..** The 4t
30190 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
301a0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 hese callbacks i
301b0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
301c0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 inters to.** [pr
301d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
301e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 value] objects.
301f0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 There is one [s
30200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
30210 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 ject for.** each
30220 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
30230 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 e SQL function.
30240 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
30250 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 are used to.** e
30260 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 xtract values fr
30270 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
30280 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
30290 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
302a0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 ines work only w
302b0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ith [protected s
302c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
302d0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 jects..** Any at
302e0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
302f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 se routines on a
30300 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 n [unprotected s
30310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
30320 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 object results
30330 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
30340 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 avior..**.** The
30350 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
30360 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 just like the c
30370 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f orresponding [co
30380 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
30390 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 tions].** except
303a0 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 that these rou
303b0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e tines take a sin
303c0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 gle [protected s
303d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
303e0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ject.** pointer
303f0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 instead of a [sq
30400 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 lite3_stmt*] poi
30410 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 nter and an inte
30420 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 ger column numbe
30430 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
30440 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
30450 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
30460 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
30470 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
30480 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
30490 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
304a0 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 achine. The.**
304b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
304c0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
304d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
304e0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
304f0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
30500 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
30510 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
30520 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
30530 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 ctively..**.** T
30540 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
30550 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 _numeric_type()
30560 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
30570 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e ts to apply.** n
30580 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 umeric affinity
30590 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 to the value. T
305a0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 his means that a
305b0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 n attempt is.**
305c0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 made to convert
305d0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 the value to an
305e0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 integer or float
305f0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a ing point. If.*
30600 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 * such a convers
30610 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 ion is possible
30620 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 without loss of
30630 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 information (in
30640 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 other.** words,
30650 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 if the value is
30660 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f a string that lo
30670 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 oks like a numbe
30680 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 r).** then the c
30690 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 onversion is per
306a0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 formed. Otherwi
306b0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e se no conversion
306c0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 occurs..** The
306d0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
306e0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
306f0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
30700 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
30710 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
30720 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
30730 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
30740 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 the pointer ret
30750 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
30760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
30770 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 b()], [sqlite3_v
30780 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 alue_text()], or
30790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
307a0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e ue_text16()] can
307b0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 be invalidated
307c0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 by a subsequent
307d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
307e0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
307f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
30800 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b ue_bytes16()], [
30810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
30820 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
30830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
30840 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 16()]..**.** The
30850 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
30860 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
30870 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
30880 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 as.** the SQL fu
30890 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 nction that supp
308a0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 lied the [sqlite
308b0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 3_value*] parame
308c0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ters..**.** INVA
308d0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
308e0 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 15103} The [sqli
308f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 te3_value_blob(V
30900 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
30910 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
30920 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
30930 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
30940 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
30950 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a BLOB and then.**
30960 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
30970 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
30980 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c he converted val
30990 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 ue..**.** {H1510
309a0 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
309b0 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 value_bytes(V)]
309c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
309d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
309e0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 number of byte
309f0 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 s in the BLOB or
30a00 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 string (exclusi
30a10 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ve of the.**
30a20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 zero termi
30a30 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 nator on the str
30a40 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 ing) that was re
30a50 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
30a60 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 most r
30a70 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
30a80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
30a90 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 b(V)] or.**
30aa0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 [sqlite3_va
30ab0 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a lue_text(V)]..**
30ac0 0a 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54 68 65 .** {H15109} The
30ad0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30ae0 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 bytes16(V)] inte
30af0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
30b00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 e.** nu
30b10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
30b20 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 the string (exc
30b30 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a lusive of the.**
30b40 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 zero t
30b50 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 erminator on the
30b60 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 string) that wa
30b70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
30b80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f e.** mo
30b90 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
30ba0 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 o [sqlite3_value
30bb0 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 _text16(V)],.**
30bc0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
30bd0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
30be0 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 (V)], or [sqlite
30bf0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
30c00 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 (V)]..**.** {H15
30c10 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 112} The [sqlite
30c20 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 3_value_double(V
30c30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
30c40 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
30c50 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
30c60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
30c70 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
30c80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
30c90 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 alue and.**
30ca0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 returns a c
30cb0 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 opy of that valu
30cc0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 e..**.** {H15115
30cd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
30ce0 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 alue_int(V)] int
30cf0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
30d00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
30d10 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
30d20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30d30 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 V into a 64-bit
30d40 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
30d50 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
30d60 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 returns the lowe
30d70 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 r 32 bits of tha
30d80 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a t integer..**.**
30d90 20 7b 48 31 35 31 31 38 7d 20 54 68 65 20 5b 73 {H15118} The [s
30da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
30db0 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 64(V)] interface
30dc0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
30dd0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
30de0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
30df0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
30e00 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 o a 64-bit signe
30e10 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a d integer and.**
30e20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
30e30 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 s a copy of that
30e40 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
30e50 7b 48 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 {H15121} The [sq
30e60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
30e70 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 (V)] interface c
30e80 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 onverts the.**
30e90 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 [protect
30ea0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
30eb0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 ] object V into
30ec0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
30ed0 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 d UTF-8.**
30ee0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 string and r
30ef0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
30f00 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e to that string.
30f10 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20 .**.** {H15124}
30f20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
30f30 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e ue_text16(V)] in
30f40 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
30f50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
30f60 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
30f70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
30f80 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d t V into a zero-
30f90 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 terminated 2-byt
30fa0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c e.** al
30fb0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 igned UTF-16 nat
30fc0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a ive byte order.*
30fd0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e * strin
30fe0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 g and returns a
30ff0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
31000 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 string..**.** {H
31010 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 15127} The [sqli
31020 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
31030 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 be(V)] interface
31040 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
31050 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
31060 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
31070 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
31080 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
31090 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 ted 2-byte.**
310a0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 aligned U
310b0 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e TF-16 big-endian
310c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 .** str
310d0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ing and returns
310e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
310f0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 t string..**.**
31100 7b 48 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 {H15130} The [sq
31110 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
31120 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 16le(V)] interfa
31130 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
31140 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f ** [pro
31150 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
31160 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 alue] object V i
31170 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 nto a zero-termi
31180 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 nated 2-byte.**
31190 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 aligned
311a0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 UTF-16 little-e
311b0 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ndian.**
311c0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 string and ret
311d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
311e0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a o that string..*
311f0 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54 68 *.** {H15133} Th
31200 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
31210 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 _type(V)] interf
31220 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 ace returns.**
31230 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b one of [
31240 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 SQLITE_NULL], [S
31250 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 QLITE_INTEGER],
31260 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a [SQLITE_FLOAT],.
31270 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
31280 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 ITE_TEXT], or [S
31290 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 QLITE_BLOB] as a
312a0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a ppropriate for.*
312b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
312c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
312d0 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b bject V..**.** {
312e0 48 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c H15136} The [sql
312f0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
31300 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 ic_type(V)] inte
31310 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a rface converts.*
31320 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
31330 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
31340 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
31350 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e V into either an
31360 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 integer or.**
31370 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 a floati
31380 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 ng point value i
31390 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 f it can do so w
313a0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a ithout loss of.*
313b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 * infor
313c0 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 mation, and retu
313d0 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 rns one of [SQLI
313e0 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 TE_NULL],.**
313f0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e [SQLITE_IN
31400 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f TEGER], [SQLITE_
31410 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f FLOAT], [SQLITE_
31420 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 TEXT], or.**
31430 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c [SQLITE_BL
31440 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 OB] as appropria
31450 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 te for the.**
31460 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 [protecte
31470 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
31480 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 object V after
31490 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 the conversion a
314a0 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 ttempt..*/.const
314b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
314c0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 alue_blob(sqlite
314d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
314e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
314f0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 es(sqlite3_value
31500 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
31510 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 value_bytes16(sq
31520 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 lite3_value*);.d
31530 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 ouble sqlite3_va
31540 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 lue_double(sqlit
31550 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
31560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
31570 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
31580 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
31590 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
315a0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c nt64(sqlite3_val
315b0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 ue*);.const unsi
315c0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 gned char *sqlit
315d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 e3_value_text(sq
315e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
315f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
31600 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
31610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
31620 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
31630 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
31640 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6le(sqlite3_valu
31650 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
31660 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
31670 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
31680 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
31690 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
316a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
316b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
316c0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
316d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
316e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
316f0 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 : Obtain Aggrega
31700 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 te Function Cont
31710 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 ext {H16210} <S2
31720 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0200>.**.** The
31730 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
31740 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 f aggregate SQL
31750 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 functions use th
31760 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c is routine to al
31770 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 locate.** a stru
31780 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e cture for storin
31790 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a g their state..*
317a0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 *.** The first t
317b0 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f ime the sqlite3_
317c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
317d0 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 t() routine is c
317e0 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 alled for a.** p
317f0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 articular aggreg
31800 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f ate, SQLite allo
31810 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 cates nBytes of
31820 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f memory, zeroes o
31830 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 ut that.** memor
31840 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 y, and returns a
31850 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 pointer to it.
31860 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 On second and su
31870 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
31880 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 o.** sqlite3_agg
31890 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
318a0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 for the same ag
318b0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
318c0 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 index,.** the s
318d0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 ame buffer is re
318e0 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c turned. The impl
318f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
31900 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 e aggregate can
31910 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 use.** the retur
31920 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 ned buffer to ac
31930 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a cumulate data..*
31940 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f *.** SQLite auto
31950 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 matically frees
31960 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 the allocated bu
31970 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 ffer when the ag
31980 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 gregate.** query
31990 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a concludes..**.*
319a0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
319b0 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 meter should be
319c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
319d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
319e0 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e t | SQL function
319f0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 context] that i
31a00 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
31a10 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 meter.** to the
31a20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 callback routine
31a30 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
31a40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 the aggregate f
31a50 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
31a60 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
31a70 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
31a80 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
31a90 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
31aa0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
31ab0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
31ac0 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 g..**.** INVARIA
31ad0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 NTS:.**.** {H162
31ae0 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 11} The first in
31af0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
31b00 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
31b10 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 ontext(C,N)] for
31b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 .** a p
31b30 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e articular instan
31b40 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 ce of an aggrega
31b50 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 te function (for
31b60 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
31b70 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 contex
31b80 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 t C) causes SQLi
31b90 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e te to allocate N
31ba0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
31bb0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 ,.** ze
31bc0 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 ro that memory,
31bd0 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 and return a poi
31be0 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f nter to the allo
31bf0 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a cated memory..**
31c00 0a 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49 66 20 .** {H16213} If
31c10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
31c20 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ion error occurs
31c30 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 during.**
31c40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 [sqlite3_agg
31c50 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
31c60 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 ,N)] then the fu
31c70 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 nction returns 0
31c80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35 7d ..**.** {H16215}
31c90 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 Second and subs
31ca0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
31cb0 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 ns of.**
31cc0 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 [sqlite3_aggre
31cd0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
31ce0 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 )] for the same
31cf0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 context pointer
31d00 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 C.** ig
31d10 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d nore the N param
31d20 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 eter and return
31d30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
31d40 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 same.**
31d50 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 block of memor
31d60 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 y returned by th
31d70 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 e first invocati
31d80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 on..**.** {H1621
31d90 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 7} The memory al
31da0 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 located by [sqli
31db0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
31dc0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a ntext(C,N)] is.*
31dd0 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d * autom
31de0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f atically freed o
31df0 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 n the next call
31e00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
31e10 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 t()].**
31e20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
31e30 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 alize()] for the
31e40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31e50 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 ment] containing
31e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
31e70 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
31e80 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 ion associated w
31e90 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a ith context C..*
31ea0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
31eb0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
31ec0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
31ed0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b t*, int nBytes);
31ee0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31ef0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 : User Data For
31f00 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 Functions {H1624
31f10 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
31f20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 * The sqlite3_us
31f30 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 er_data() interf
31f40 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
31f50 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
31f60 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 nter that was th
31f70 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 e pUserData para
31f80 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 meter (the 5th p
31f90 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
31fa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
31fb0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
31fc0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
31fd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
31fe0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
31ff0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
32000 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
32010 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
32020 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 ned function. {E
32030 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 ND}.**.** This r
32040 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 outine must be c
32050 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
32060 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
32070 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 ich.** the appli
32080 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
32090 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
320a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ng..**.** INVARI
320b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ANTS:.**.** {H16
320c0 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 243} The [sqlite
320d0 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20 3_user_data(C)]
320e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
320f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
32100 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70 6f ** P po
32110 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b inter from the [
32120 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
32130 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c unction(D,X,N,E,
32140 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 P,F,S,L)].**
32150 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 or [sqlite
32160 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
32170 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c n16(D,X,N,E,P,F,
32180 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a S,L)] call that.
32190 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 ** regi
321a0 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 stered the SQL f
321b0 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 unction associat
321c0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 ed with [sqlite3
321d0 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a _context] C..*/.
321e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 void *sqlite3_us
321f0 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f er_data(sqlite3_
32200 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a context*);../*.*
32210 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
32220 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
32230 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 For Functions {H
32240 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 16250} <S60600><
32250 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20200>.**.** Th
32260 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e sqlite3_contex
32270 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e t_db_handle() in
32280 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
32290 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
322a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
322b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
322c0 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 tion] (the 1st p
322d0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
322e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
322f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
32300 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
32310 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
32320 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
32330 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
32340 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
32350 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
32360 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ned function..**
32370 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
32380 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20 54 **.** {H16253} T
32390 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
323a0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 ext_db_handle(C)
323b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
323c0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 rns a copy of th
323d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 e.** D
323e0 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 pointer from the
323f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
32400 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c _function(D,X,N,
32410 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 E,P,F,S,L)].**
32420 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 or [sqli
32430 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
32440 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c ion16(D,X,N,E,P,
32450 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 F,S,L)] call tha
32460 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 t.** re
32470 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c gistered the SQL
32480 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 function associ
32490 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 ated with [sqlit
324a0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a e3_context] C..*
324b0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
324c0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
324d0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e ndle(sqlite3_con
324e0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 text*);../*.** C
324f0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
32500 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 n Auxiliary Data
32510 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30 {H16270} <S2020
32520 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 0>.**.** The fol
32530 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 lowing two funct
32540 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 ions may be used
32550 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 by scalar SQL f
32560 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 unctions to.** a
32570 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 ssociate metadat
32580 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 a with argument
32590 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 values. If the s
325a0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 ame value is pas
325b0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 sed to.** multip
325c0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f le invocations o
325d0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 f the same SQL f
325e0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 unction during q
325f0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 uery execution,
32600 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 under.** some ci
32610 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 rcumstances the
32620 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 associated metad
32630 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 ata may be prese
32640 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a rved. This may.*
32650 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 * be used, for e
32660 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 xample, to add a
32670 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 regular-express
32680 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 ion matching sca
32690 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e lar.** function.
326a0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 The compiled ve
326b0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 rsion of the reg
326c0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 ular expression
326d0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 is stored as.**
326e0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
326f0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c ted with the SQL
32700 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
32710 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 the regular exp
32720 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 ression.** patte
32730 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 rn. The compile
32740 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 d regular expres
32750 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 sion can be reus
32760 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a ed on multiple.*
32770 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 * invocations of
32780 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
32790 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f on so that the o
327a0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 riginal pattern
327b0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e string.** does n
327c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 ot need to be re
327d0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 compiled on each
327e0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a invocation..**.
327f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
32800 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
32810 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
32820 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
32830 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f metadata.** asso
32840 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 ciated by the sq
32850 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
32860 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 a() function wit
32870 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 h the Nth argume
32880 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 nt.** value to t
32890 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
328a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
328b0 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 If no metadata
328c0 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a has been ever.**
328d0 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 been set for th
328e0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f e Nth argument o
328f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 f the function,
32900 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 or if the corres
32910 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 ponding.** funct
32920 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 ion parameter ha
32930 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 s changed since
32940 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 the meta-data wa
32950 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 s set,.** then s
32960 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
32970 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e ta() returns a N
32980 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
32990 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ** The sqlite3_s
329a0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
329b0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 erface saves the
329c0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 metadata.** poi
329d0 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 nted to by its 3
329e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 rd parameter as
329f0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 the metadata for
32a00 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 the N-th.** arg
32a10 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 ument of the app
32a20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
32a30 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 function. Subs
32a40 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 equent.** calls
32a50 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 to sqlite3_get_a
32a60 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 uxdata() might r
32a70 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c eturn this data,
32a80 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f if it has.** no
32a90 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 t been destroyed
32aa0 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f ..** If it is no
32ab0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 t NULL, SQLite w
32ac0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 ill invoke the d
32ad0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e estructor.** fun
32ae0 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 ction given by t
32af0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
32b00 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f to sqlite3_set_
32b10 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 auxdata() on.**
32b20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 the metadata whe
32b30 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 n the correspond
32b40 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 ing function par
32b50 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a ameter changes.*
32b60 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 * or when the SQ
32b70 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 L statement comp
32b80 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 letes, whichever
32b90 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a comes first..**
32ba0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 .** SQLite is fr
32bb0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 ee to call the d
32bc0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 estructor and dr
32bd0 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 op metadata on a
32be0 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 ny.** parameter
32bf0 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 of any function
32c00 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 at any time. Th
32c10 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 e only guarantee
32c20 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 is that.** the
32c30 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 destructor will
32c40 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 be called before
32c50 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 the metadata is
32c60 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 dropped..**.**
32c70 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 In practice, met
32c80 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 adata is preserv
32c90 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 ed between funct
32ca0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a ion calls for.**
32cb0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 expressions tha
32cc0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 t are constant a
32cd0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 t compile time.
32ce0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 This includes li
32cf0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 teral.** values
32d00 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 and SQL variable
32d10 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
32d20 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
32d30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
32d40 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
32d50 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 hich.** the SQL
32d60 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
32d70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ing..**.** INVAR
32d80 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
32d90 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 6272} The [sqlit
32da0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 e3_get_auxdata(C
32db0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
32dc0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
32dd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 .** to
32de0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
32df0 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 ted with the Nth
32e00 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 parameter of th
32e10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a e SQL function.*
32e20 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 * whose
32e30 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f context is C, o
32e40 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 r NULL if there
32e50 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 is no metadata a
32e60 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 ssociated.**
32e70 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74 20 with that
32e80 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
32e90 20 7b 48 31 36 32 37 34 7d 20 54 68 65 20 5b 73 {H16274} The [s
32ea0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
32eb0 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 ta(C,N,P,D)] int
32ec0 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 erface assigns a
32ed0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 metadata.**
32ee0 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 pointer P
32ef0 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d to the Nth param
32f00 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 eter of the SQL
32f10 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f function with co
32f20 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b ntext C..**.** {
32f30 48 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 H16276} SQLite w
32f40 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 ill invoke the d
32f50 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 estructor D with
32f60 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
32f70 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 nt.** w
32f80 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 hich is the meta
32f90 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 data pointer P f
32fa0 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 ollowing a call
32fb0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b to.** [
32fc0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
32fd0 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 ata(C,N,P,D)] wh
32fe0 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 en SQLite ceases
32ff0 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 to hold.**
33000 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 the metadat
33010 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 a..**.** {H16277
33020 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 } SQLite ceases
33030 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 to hold metadata
33040 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 for an SQL func
33050 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a tion parameter.*
33060 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 * when
33070 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 the value of tha
33080 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e t parameter chan
33090 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 ges..**.** {H162
330a0 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 78} When [sqlite
330b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 3_set_auxdata(C,
330c0 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b N,P,D)] is invok
330d0 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 ed, the destruct
330e0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 or.** i
330f0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 s called for any
33100 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 prior metadata
33110 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
33120 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
33130 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f n.** co
33140 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 ntext C and para
33150 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b meter N..**.** {
33160 48 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 H16279} SQLite w
33170 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 ill call destruc
33180 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 tors for any met
33190 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 adata it is hold
331a0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
331b0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 in a particular
331c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
331d0 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 ent] S when eith
331e0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b er.** [
331f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
33200 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
33210 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 nalize(S)] is ca
33220 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 lled..*/.void *s
33230 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
33240 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
33250 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 xt*, int N);.voi
33260 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 d sqlite3_set_au
33270 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f xdata(sqlite3_co
33280 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 ntext*, int N, v
33290 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 oid*, void (*)(v
332a0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 oid*));.../*.**
332b0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 CAPI3REF: Consta
332c0 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 nts Defining Spe
332d0 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 cial Destructor
332e0 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 Behavior {H10280
332f0 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S30100>.**.**
33300 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 These are speci
33310 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 al values for th
33320 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 e destructor tha
33330 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 t is passed in a
33340 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 s the.** final a
33350 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 rgument to routi
33360 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
33370 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 3_result_blob()]
33380 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75 . If the destru
33390 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 ctor.** argument
333a0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 is SQLITE_STATI
333b0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 C, it means that
333c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 the content poi
333d0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 nter is constant
333e0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 .** and will nev
333f0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 er change. It d
33400 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
33410 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 be destroyed. T
33420 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 he.** SQLITE_TRA
33430 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 NSIENT value mea
33440 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
33450 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ent will likely
33460 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 change in.** the
33470 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 near future and
33480 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f that SQLite sho
33490 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e uld make its own
334a0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
334b0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
334c0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 before returning
334d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 ..**.** The type
334e0 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 def is necessary
334f0 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 to work around
33500 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 problems in cert
33510 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 ain.** C++ compi
33520 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 lers. See ticke
33530 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 t #2191..*/.type
33540 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
33550 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
33560 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 pe)(void*);.#def
33570 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ine SQLITE_STATI
33580 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 C ((sqlite3
33590 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
335a0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 )0).#define SQLI
335b0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 TE_TRANSIENT (
335c0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
335d0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a tor_type)-1)../*
335e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
335f0 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 tting The Result
33600 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 Of An SQL Funct
33610 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 ion {H16400} <S2
33620 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0200>.**.** Thes
33630 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
33640 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 sed by the xFunc
33650 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 or xFinal callb
33660 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 acks that.** imp
33670 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 lement SQL funct
33680 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
33690 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 tes. See.** [sq
336a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
336b0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
336c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
336d0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f ction16()].** fo
336e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
336f0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
33700 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
33710 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c work very much l
33720 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 ike the [paramet
33730 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 er binding] fami
33740 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f ly of.** functio
33750 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 ns used to bind
33760 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 values to host p
33770 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 arameters in pre
33780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
33790 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 ..** Refer to th
337a0 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 e [SQL parameter
337b0 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
337c0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
337d0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
337e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
337f0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 sult_blob() inte
33800 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
33810 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e esult from.** an
33820 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
33830 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
33840 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f be the BLOB who
33850 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f se content is po
33860 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 inted.** to by t
33870 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
33880 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 ter and which is
33890 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 N bytes long wh
338a0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 ere N is the.**
338b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e third parameter.
338c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
338d0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
338e0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 ob() interfaces
338f0 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f set the result o
33900 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
33910 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
33920 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c ction to be a BL
33930 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c OB containing al
33940 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 l zero.** bytes
33950 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 and N bytes in s
33960 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 ize, where N is
33970 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
33980 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2nd parameter..
33990 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
339a0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
339b0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
339c0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
339d0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
339e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
339f0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 ion to be a floa
33a00 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
33a10 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
33a20 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
33a30 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c t..**.** The sql
33a40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33a50 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f r() and sqlite3_
33a60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
33a70 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 functions.** ca
33a80 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e use the implemen
33a90 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ted SQL function
33aa0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 to throw an exc
33ab0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 eption..** SQLit
33ac0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e e uses the strin
33ad0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 g pointed to by
33ae0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d the.** 2nd param
33af0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
33b00 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
33b10 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
33b20 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 _error16().** as
33b30 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 the text of an
33b40 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 error message.
33b50 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 SQLite interpret
33b60 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
33b70 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 essage string fr
33b80 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
33b90 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 t_error() as UTF
33ba0 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e -8. SQLite.** in
33bb0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 terprets the str
33bc0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ing from sqlite3
33bd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
33be0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e ) as UTF-16 in n
33bf0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 ative.** byte or
33c00 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 der. If the thi
33c10 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
33c20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33c30 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
33c40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33c50 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 r16() is negativ
33c60 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
33c70 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 kes as the error
33c80 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 .** message all
33c90 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 text up through
33ca0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
33cb0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 haracter..** If
33cc0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
33cd0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
33ce0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 esult_error() or
33cf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
33d00 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 lt_error16() is
33d10 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 non-negative the
33d20 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 n SQLite takes t
33d30 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 hat many.** byte
33d40 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 s (not character
33d50 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 s) from the 2nd
33d60 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 parameter as the
33d70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
33d80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
33d90 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e esult_error() an
33da0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
33db0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f _error16().** ro
33dc0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 utines make a pr
33dd0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
33de0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
33df0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 text before.** t
33e00 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e hey return. Hen
33e10 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ce, the calling
33e20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 function can dea
33e30 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f llocate or.** mo
33e40 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 dify the text af
33e50 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 ter they return
33e60 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a without harm..**
33e70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
33e80 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 ult_error_code()
33e90 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 function change
33ea0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
33eb0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
33ec0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 SQLite as a resu
33ed0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 lt of an error i
33ee0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 n a function. B
33ef0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 y default,.** th
33f00 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 e error code is
33f10 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 SQLITE_ERROR. A
33f20 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
33f30 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
33f40 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
33f50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33f60 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 error16() resets
33f70 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
33f80 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e to SQLITE_ERROR.
33f90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
33fa0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 e3_result_toobig
33fb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 () interface cau
33fc0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 ses SQLite to th
33fd0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 row an error.**
33fe0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 indicating that
33ff0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 a string or BLOB
34000 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 is to long to r
34010 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 epresent..**.**
34020 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
34030 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 lt_nomem() inter
34040 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 face causes SQLi
34050 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 te to throw an e
34060 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 rror.** indicati
34070 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 ng that a memory
34080 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
34090 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
340a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
340b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
340c0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
340d0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
340e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
340f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
34100 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 the 32-bit signe
34110 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
34120 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
34130 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
34140 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
34150 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 ult_int64() inte
34160 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
34170 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
34180 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
34190 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
341a0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d on to be the 64-
341b0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
341c0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
341d0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
341e0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
341f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34200 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 null() interface
34210 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
34220 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
34230 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
34240 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
34250 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
34260 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
34270 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 lt_text(), sqlit
34280 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
34290 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 (),.** sqlite3_r
342a0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 esult_text16le()
342b0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 , and sqlite3_re
342c0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 sult_text16be()
342d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 interfaces.** se
342e0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c t the return val
342f0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ue of the applic
34300 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
34310 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 nction to be.**
34320 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 a text string wh
34330 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 ich is represent
34340 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 ed as UTF-8, UTF
34350 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
34360 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 order,.** UTF-16
34370 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 little endian,
34380 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e or UTF-16 big en
34390 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 dian, respective
343a0 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 ly..** SQLite ta
343b0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 kes the text res
343c0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 ult from the app
343d0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a lication from.**
343e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
343f0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 er of the sqlite
34400 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
34410 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 nterfaces..** If
34420 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
34430 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
34440 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
34450 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
34460 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 negative, then S
34470 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 QLite takes resu
34480 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 lt text from the
34490 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2nd parameter.*
344a0 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 * through the fi
344b0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
344c0 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 er..** If the 3r
344d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
344e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
344f0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
34500 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 es.** is non-neg
34510 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d ative, then as m
34520 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 any bytes (not c
34530 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 haracters) of th
34540 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 e text.** pointe
34550 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 d to by the 2nd
34560 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 parameter are ta
34570 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 ken as the appli
34580 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a cation-defined.*
34590 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c * function resul
345a0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 t..** If the 4th
345b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
345c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
345d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
345e0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
345f0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 result_blob is a
34600 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
34610 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 r, then SQLite c
34620 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e alls that.** fun
34630 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 ction as the des
34640 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 tructor on the t
34650 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 ext or BLOB resu
34660 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a lt when it has.*
34670 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 * finished using
34680 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
34690 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 If the 4th para
346a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
346b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
346c0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a * interfaces or.
346d0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
346e0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
346f0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
34700 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 QLITE_STATIC, th
34710 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 en SQLite.** ass
34720 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 umes that the te
34730 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
34740 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 t is in constant
34750 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
34760 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 not.** copy the
34770 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 it or call a des
34780 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 tructor when it
34790 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
347a0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a ng that result..
347b0 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 ** If the 4th pa
347c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
347d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
347e0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
347f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
34800 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 ult_blob is the
34810 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 special constant
34820 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
34830 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 T.** then SQLite
34840 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
34850 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f the result into
34860 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 space obtained
34870 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 from.** from [sq
34880 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
34890 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e before it return
348a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
348b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
348c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
348d0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 ts the result of
348e0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
348f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
34900 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 tion to be a cop
34910 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 y the.** [unprot
34920 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
34930 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 lue] object spec
34940 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 ified by the 2nd
34950 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 parameter. The
34960 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
34970 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
34980 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 face makes a cop
34990 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 y of the [sqlite
349a0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 3_value].** so t
349b0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
349c0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 _value] specifie
349d0 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 d in the paramet
349e0 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 er may change or
349f0 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 .** be deallocat
34a00 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
34a10 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
34a20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 returns without
34a30 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 harm..** A [prot
34a40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
34a50 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 lue] object may
34a60 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 always be used w
34a70 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 here an.** [unpr
34a80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
34a90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 value] object is
34aa0 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 required, so ei
34ab0 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 ther.** kind of
34ac0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
34ad0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 object can be us
34ae0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 ed with this int
34af0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 erface..**.** If
34b00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
34b10 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 are called from
34b20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 within the diffe
34b30 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 rent thread.** t
34b40 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 han the one cont
34b50 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 aining the appli
34b60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
34b70 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 unction that rec
34b80 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 eived.** the [sq
34b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 lite3_context] p
34ba0 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 ointer, the resu
34bb0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
34bc0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 d..**.** INVARIA
34bd0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 NTS:.**.** {H164
34be0 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 03} The default
34bf0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
34c00 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 m any SQL functi
34c10 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a on is NULL..**.*
34c20 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b * {H16406} The [
34c30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
34c40 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e lob(C,V,N,D)] in
34c50 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 terface changes
34c60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
34c70 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
34c80 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
34c90 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20 a BLOB that is
34ca0 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 N bytes.**
34cb0 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e in length an
34cc0 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 d with content p
34cd0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a ointed to by V..
34ce0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54 **.** {H16409} T
34cf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
34d00 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 lt_double(C,V)]
34d10 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
34d20 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
34d30 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f return value o
34d40 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 f function C to
34d50 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 be the floating
34d60 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a point value V..*
34d70 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68 *.** {H16412} Th
34d80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
34d90 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 t_error(C,V,N)]
34da0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
34db0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 s the return.**
34dc0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f value o
34dd0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 f function C to
34de0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 be an exception
34df0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a with error code.
34e00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
34e10 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 ITE_ERROR] and a
34e20 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73 UTF-8 error mes
34e30 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d sage copied from
34e40 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 V up to the.**
34e50 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a first z
34e60 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 ero byte or unti
34e70 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 l N bytes are re
34e80 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 ad if N is posit
34e90 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 ive..**.** {H164
34ea0 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 15} The [sqlite3
34eb0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
34ec0 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 C,V,N)] interfac
34ed0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 e changes the re
34ee0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
34ef0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 value of functi
34f00 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 on C to be an ex
34f10 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 ception with err
34f20 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 or code.**
34f30 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f [SQLITE_ERRO
34f40 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 R] and a UTF-16
34f50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
34f60 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a r error message.
34f70 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 ** copi
34f80 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 ed from V up to
34f90 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 the first zero t
34fa0 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 erminator or unt
34fb0 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 il N bytes.**
34fc0 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64 20 are read
34fd0 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 if N is positive
34fe0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d ..**.** {H16418}
34ff0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
35000 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 sult_error_toobi
35010 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 g(C)] interface
35020 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 changes the retu
35030 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 rn.** v
35040 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 alue of the func
35050 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 tion C to be an
35060 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 exception with e
35070 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 rror code.**
35080 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f [SQLITE_TO
35090 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 OBIG] and an app
350a0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d ropriate error m
350b0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 essage..**.** {H
350c0 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 16421} The [sqli
350d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
350e0 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 _nomem(C)] inter
350f0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 face changes the
35100 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
35110 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 value of the
35120 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
35130 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 e an exception w
35140 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a ith error code.*
35150 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
35160 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e TE_NOMEM] and an
35170 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 appropriate err
35180 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
35190 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b * {H16424} The [
351a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
351b0 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 rror_code(C,E)]
351c0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
351d0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 s the return.**
351e0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f value o
351f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 f the function C
35200 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 to be an except
35210 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 ion with error c
35220 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 ode E..**
35230 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 The error mes
35240 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 sage text is unc
35250 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 hanged..**.** {H
35260 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 16427} The [sqli
35270 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 te3_result_int(C
35280 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,V)] interface c
35290 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
352a0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
352b0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
352c0 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 C to be the 32-b
352d0 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 it integer value
352e0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 V..**.** {H1643
352f0 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 0} The [sqlite3_
35300 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 result_int64(C,V
35310 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 )] interface cha
35320 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 nges the.**
35330 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 return valu
35340 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 e of function C
35350 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 to be the 64-bit
35360 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 integer value V
35370 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d ..**.** {H16433}
35380 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
35390 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e sult_null(C)] in
353a0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 terface changes
353b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
353c0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
353d0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
353e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 NULL..**.** {H1
353f0 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 6436} The [sqlit
35400 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 e3_result_text(C
35410 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 ,V,N,D)] interfa
35420 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ce changes the.*
35430 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
35440 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 n value of funct
35450 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 ion C to be the
35460 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
35470 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74 6f V up to
35480 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
35490 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 if N is negative
354a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
354b0 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 the first N byte
354c0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e s of V if N is n
354d0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a on-negative..**.
354e0 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20 ** {H16439} The
354f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
35500 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d text16(C,V,N,D)]
35510 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 interface chang
35520 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 es the.**
35530 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 return value
35540 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f of function C to
35550 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e be the UTF-16 n
35560 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
35570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 .** str
35580 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 ing V up to the
35590 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 first zero if N
355a0 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 is negative.**
355b0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 or the f
355c0 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 irst N bytes of
355d0 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 V if N is non-ne
355e0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 gative..**.** {H
355f0 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 16442} The [sqli
35600 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
35610 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 6be(C,V,N,D)] in
35620 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 terface changes
35630 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
35640 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
35650 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
35660 20 74 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d the UTF-16 big-
35670 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 endian.**
35680 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 string V up t
35690 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
356a0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 if N is negativ
356b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 e.** or
356c0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 the first N byt
356d0 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 es or V if N is
356e0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a non-negative..**
356f0 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65 .** {H16445} The
35700 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35710 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c _text16le(C,V,N,
35720 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 D)] interface ch
35730 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 anges the.**
35740 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c return val
35750 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
35760 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 to be the UTF-1
35770 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 6 little-endian.
35780 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 ** stri
35790 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 ng V up to the f
357a0 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 irst zero if N i
357b0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 s negative.**
357c0 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 or the fi
357d0 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 rst N bytes of V
357e0 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 if N is non-neg
357f0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
35800 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 6448} The [sqlit
35810 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
35820 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 C,V)] interface
35830 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 changes the.**
35840 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 return v
35850 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e alue of function
35860 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e C to be the [un
35870 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
35880 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 3_value].**
35890 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a object V..*
358a0 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68 *.** {H16451} Th
358b0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
358c0 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d t_zeroblob(C,N)]
358d0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 interface chang
358e0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 es the.**
358f0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 return value
35900 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f of function C to
35910 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c be an N-byte BL
35920 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e OB of all zeros.
35930 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20 .**.** {H16454}
35940 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
35950 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 ult_error()] and
35960 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35970 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 _error16()].**
35980 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
35990 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f es make a copy o
359a0 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 f their error me
359b0 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 ssage strings be
359c0 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 fore.**
359d0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a returning..**.*
359e0 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68 * {H16457} If th
359f0 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 e D destructor p
35a00 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
35a10 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
35a20 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 (C,V,N,D)],.**
35a30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
35a40 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 _result_text(C,V
35a50 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ,N,D)], [sqlite3
35a60 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 _result_text16(C
35a70 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,V,N,D)],.**
35a80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 [sqlite3_r
35a90 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 esult_text16be(C
35aa0 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 ,V,N,D)], or.**
35ab0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
35ac0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 3_result_text16l
35ad0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 e(C,V,N,D)] is t
35ae0 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c he constant [SQL
35af0 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 ITE_STATIC].**
35b00 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 then no
35b10 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 destructor is ev
35b20 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 er called on the
35b30 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 pointer V and S
35b40 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 QLite.**
35b50 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 assumes that V
35b60 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a is immutable..*
35b70 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66 *.** {H16460} If
35b80 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f the D destructo
35b90 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b r parameter to [
35ba0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
35bb0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a lob(C,V,N,D)],.*
35bc0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
35bd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 te3_result_text(
35be0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 C,V,N,D)], [sqli
35bf0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
35c00 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 6(C,V,N,D)],.**
35c10 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
35c20 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
35c30 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a e(C,V,N,D)], or.
35c40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
35c50 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
35c60 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 16le(C,V,N,D)] i
35c70 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a s the constant.*
35c80 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
35c90 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 TE_TRANSIENT] th
35ca0 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 en the interface
35cb0 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f s makes a copy o
35cc0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
35cd0 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 content of V a
35ce0 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 nd retains the c
35cf0 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 opy..**.** {H164
35d00 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 63} If the D des
35d10 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 tructor paramete
35d20 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 r to [sqlite3_re
35d30 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c sult_blob(C,V,N,
35d40 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
35d50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35d60 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c _text(C,V,N,D)],
35d70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35d80 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 _text16(C,V,N,D)
35d90 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
35da0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35db0 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 ext16be(C,V,N,D)
35dc0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
35dd0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c [sqlite3_resul
35de0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e t_text16le(C,V,N
35df0 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c ,D)] is some val
35e00 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a ue other than.**
35e10 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 6f the co
35e20 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f nstants [SQLITE_
35e30 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c STATIC] and [SQL
35e40 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 ITE_TRANSIENT] t
35e50 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
35e60 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f SQLite will invo
35e70 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ke the destructo
35e80 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74 r D with V as it
35e90 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a s only argument.
35ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e ** when
35eb0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
35ec0 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 with the V valu
35ed0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 e..*/.void sqlit
35ee0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 e3_result_blob(s
35ef0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35f00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
35f10 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
35f20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
35f30 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 _result_double(s
35f40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35f50 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 double);.void s
35f60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
35f70 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ror(sqlite3_cont
35f80 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 ext*, const char
35f90 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
35fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
35fb0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e or16(sqlite3_con
35fc0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
35fd0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 d*, int);.void s
35fe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
35ff0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 ror_toobig(sqlit
36000 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
36010 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
36020 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 t_error_nomem(sq
36030 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
36040 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
36050 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 sult_error_code(
36060 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
36070 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
36080 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 ite3_result_int(
36090 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
360a0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
360b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
360c0 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 4(sqlite3_contex
360d0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 t*, sqlite3_int6
360e0 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 4);.void sqlite3
360f0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c _result_null(sql
36100 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
36110 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
36120 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 ult_text(sqlite3
36130 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
36140 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 char*, int, voi
36150 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
36160 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
36170 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 t_text16(sqlite3
36180 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
36190 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
361a0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
361b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
361c0 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 t_text16le(sqlit
361d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
361e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
361f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
36200 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
36210 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 lt_text16be(sqli
36220 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
36230 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
36240 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
36250 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
36260 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ult_value(sqlite
36270 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 3_context*, sqli
36280 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 te3_value*);.voi
36290 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
362a0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
362b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
362c0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 n);../*.** CAPI3
362d0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 REF: Define New
362e0 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e Collating Sequen
362f0 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 ces {H16600} <S2
36300 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0300>.**.** Thes
36310 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
36320 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 used to add new
36330 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
36340 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 ces to the.** [d
36350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
36360 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 on] specified as
36370 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
36380 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e ent..**.** The n
36390 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 ame of the new c
363a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
363b0 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 e is specified a
363c0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
363d0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f .** for sqlite3_
363e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
363f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
36400 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
36410 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 v2().** and a UT
36420 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 F-16 string for
36430 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
36440 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e ollation16(). In
36450 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 all cases.** th
36460 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 e name is passed
36470 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 as the second f
36480 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
36490 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
364a0 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 d argument may b
364b0 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e e one of the con
364c0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 stants [SQLITE_U
364d0 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 TF8],.** [SQLITE
364e0 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 _UTF16LE] or [SQ
364f0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 LITE_UTF16BE], i
36500 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 ndicating that t
36510 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 he user-supplied
36520 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 .** routine expe
36530 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 cts to be passed
36540 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
36550 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 ings encoded usi
36560 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 ng UTF-8,.** UTF
36570 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
36580 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
36590 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 -endian, respect
365a0 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 ively. The.** th
365b0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 ird argument mig
365c0 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 ht also be [SQLI
365d0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
365e0 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 ] to indicate th
365f0 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e at.** the routin
36600 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 e expects pointe
36610 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 rs to 16-bit wor
36620 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 d aligned string
36630 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 s.** of UTF-16 i
36640 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
36650 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 e order of the h
36660 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a ost computer..**
36670 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
36680 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 the user suppli
36690 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 ed routine must
366a0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
366b0 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 fifth.** argume
366c0 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 nt. If it is NU
366d0 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 LL, this is the
366e0 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 same as deleting
366f0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a the collation.*
36700 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 * sequence (so t
36710 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f hat SQLite canno
36720 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 t call it anymor
36730 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 e)..** Each time
36740 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36750 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 supplied functi
36760 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 on is invoked, i
36770 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 t is passed.** a
36780 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 s its first para
36790 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 meter a copy of
367a0 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 the void* passed
367b0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 as the fourth a
367c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 rgument.** to sq
367d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
367e0 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 lation() or sqli
367f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
36800 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 tion16()..**.**
36810 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 The remaining ar
36820 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 guments to the a
36830 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
36840 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 ied routine are
36850 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 two strings,.**
36860 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 each represented
36870 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 by a (length, d
36880 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e ata) pair and en
36890 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 coded in the enc
368a0 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 oding.** that wa
368b0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
368c0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 third argument w
368d0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f hen the collatio
368e0 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a n sequence was.*
368f0 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 * registered. {E
36900 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 ND} The applica
36910 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c tion defined col
36920 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 lation routine s
36930 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
36940 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f negative, zero o
36950 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 r positive if th
36960 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 e first string i
36970 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 s less than,.**
36980 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 equal to, or gre
36990 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 ater than the se
369a0 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 cond string. i.e
369b0 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 . (STRING1 - STR
369c0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ING2)..**.** The
369d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
369e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 collation_v2() w
369f0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
36a00 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36a10 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 on().** except t
36a20 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 hat it takes an
36a30 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 extra argument w
36a40 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 hich is a destru
36a50 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ctor for.** the
36a60 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 collation. The
36a70 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 destructor is ca
36a80 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f lled when the co
36a90 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 llation is.** de
36aa0 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 stroyed and is p
36ab0 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 assed a copy of
36ac0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
36ad0 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 eter void* point
36ae0 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c er.** of the sql
36af0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
36b00 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 ation_v2()..** C
36b10 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 ollations are de
36b20 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 stroyed when the
36b30 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e y are overridden
36b40 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 by later calls
36b50 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 to the.** collat
36b60 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e ion creation fun
36b70 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 ctions or when t
36b80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
36b90 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 nection] is clos
36ba0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ed.** using [sql
36bb0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a ite3_close()]..*
36bc0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
36bd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20 .**.** {H16603}
36be0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
36bf0 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 l to the.**
36c00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 [sqlite3_cr
36c10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
36c20 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 2(B,X,E,P,F,D)]
36c30 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 interface.**
36c40 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73 20 registers
36c50 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 function F as th
36c60 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e e comparison fun
36c70 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a ction used to.**
36c80 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d implem
36c90 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 ent collation X
36ca0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
36cb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 connection] B f
36cc0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 or.** d
36cd0 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 atabases having
36ce0 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a encoding E..**.*
36cf0 2a 20 7b 48 31 36 36 30 34 7d 20 53 51 4c 69 74 * {H16604} SQLit
36d00 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 e understands th
36d10 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f e X parameter to
36d20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
36d30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
36d40 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c lation_v2(B,X,E,
36d50 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 P,F,D)] as a zer
36d60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
36d70 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 UTF-8 s
36d80 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 tring in which c
36d90 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 ase is ignored f
36da0 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63 74 or ASCII charact
36db0 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ers and.**
36dc0 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 is significa
36dd0 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 nt for non-ASCII
36de0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
36df0 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53 75 63 63 ** {H16606} Succ
36e00 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 essive calls to
36e10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
36e20 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 collation_v2(B,X
36e30 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 ,E,P,F,D)].**
36e40 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 with the
36e50 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 same values for
36e60 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 B, X, and E, ove
36e70 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 rride prior valu
36e80 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f es.** o
36e90 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a f P, F, and D..*
36ea0 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49 66 *.** {H16609} If
36eb0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
36ec0 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 D in [sqlite3_cr
36ed0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
36ee0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2(B,X,E,P,F,D)].
36ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e ** is n
36f00 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 ot NULL then it
36f10 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
36f20 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 rgument P when t
36f30 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 he.** c
36f40 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
36f50 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 n is dropped by
36f60 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 SQLite..**.** {H
36f70 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 16612} A collati
36f80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 ng function is d
36f90 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 ropped when it i
36fa0 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a s overloaded..**
36fb0 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41 20 63 .** {H16615} A c
36fc0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
36fd0 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 n is dropped whe
36fe0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
36ff0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 onnection.**
37000 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 is closed
37010 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
37020 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b lose()]..**.** {
37030 48 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e H16618} The poin
37040 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 ter P in [sqlite
37050 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
37060 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
37070 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D)].**
37080 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
37090 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 h as the first p
370a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
370b0 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 comparison.**
370c0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 function
370d0 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 F for all subseq
370e0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 uent invocations
370f0 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 of F..**.** {H1
37100 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 6621} A call to
37110 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
37120 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c collation(B,X,E,
37130 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 P,F)] is exactly
37140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
37150 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 same as a call
37160 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
37170 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
37180 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 )] with.**
37190 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 the same par
371a0 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 ameters and a NU
371b0 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a LL destructor..*
371c0 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f *.** {H16624} Fo
371d0 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 llowing a [sqlit
371e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
371f0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 ion_v2(B,X,E,P,F
37200 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ,D)],.**
37210 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 SQLite uses th
37220 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e e comparison fun
37230 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 ction F for all
37240 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a text comparison.
37250 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 ** oper
37260 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 ations on the [d
37270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
37280 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 on] B on text va
37290 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 lues that.**
372a0 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f use the co
372b0 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 llating sequence
372c0 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 named X..**.**
372d0 7b 48 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 {H16627} The [sq
372e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
372f0 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 lation16(B,X,E,P
37300 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 ,F)] works the s
37310 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ame.**
37320 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 as [sqlite3_crea
37330 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 te_collation(B,X
37340 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 ,E,P,F)] except
37350 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 that the.**
37360 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e collation n
37370 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 ame X is underst
37380 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e ood as UTF-16 in
37390 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
373a0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 er.** i
373b0 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e nstead of UTF-8.
373c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20 .**.** {H16630}
373d0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f When multiple co
373e0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f mparison functio
373f0 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 ns are available
37400 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a for the same.**
37410 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 collat
37420 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 ing sequence, SQ
37430 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 Lite chooses the
37440 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 one whose text
37450 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 encoding.**
37460 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74 68 requires th
37470 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
37480 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f f conversion fro
37490 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a m the default.**
374a0 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 65 text e
374b0 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 ncoding of the d
374c0 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 atabase..*/.int
374d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
374e0 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 ollation(. sqli
374f0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
37500 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
37510 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
37520 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 void*,. int(*xC
37530 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
37540 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
37550 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
37560 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
37570 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
37580 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 2(. sqlite3*, .
37590 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
375a0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
375b0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
375c0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
375d0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
375e0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
375f0 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 void*),. void(
37600 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
37610 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
37620 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
37630 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c n16(. sqlite3*,
37640 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a . const void *
37650 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 zName,. int eTe
37660 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c xtRep, . void*,
37670 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
37680 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
37690 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
376a0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a t void*).);../*.
376b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c ** CAPI3REF: Col
376c0 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 lation Needed Ca
376d0 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d llbacks {H16700}
376e0 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20300>.**.**
376f0 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 To avoid having
37700 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 to register all
37710 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
37720 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 ces before a dat
37730 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 abase.** can be
37740 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 used, a single c
37750 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
37760 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 may be register
37770 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
37780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
37790 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 ion] to be calle
377a0 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e d whenever an un
377b0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f defined collatio
377c0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 n.** sequence is
377d0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
377e0 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e If the function
377f0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 is registered u
37800 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
37810 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
37820 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e d() API,.** then
37830 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 it is passed th
37840 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 e names of undef
37850 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ined collation s
37860 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 equences as stri
37870 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 ngs.** encoded i
37880 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 n UTF-8. {H16703
37890 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c } If sqlite3_col
378a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
378b0 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 ) is used,.** th
378c0 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 e names are pass
378d0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
378e0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 machine native b
378f0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 yte order..** A
37900 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 call to either f
37910 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 unction replaces
37920 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 any existing ca
37930 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 llback..**.** Wh
37940 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
37950 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 is invoked, the
37960 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 first argument p
37970 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a assed is a copy.
37980 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ** of the second
37990 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
379a0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
379b0 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 eeded() or.** sq
379c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
379d0 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 needed16(). The
379e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
379f0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
37a00 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
37a10 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
37a20 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 ent is one of [S
37a30 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 QLITE_UTF8], [SQ
37a40 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a LITE_UTF16BE],.*
37a50 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 * or [SQLITE_UTF
37a60 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 16LE], indicatin
37a70 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 g the most desir
37a80 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 able form of the
37a90 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
37aa0 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 quence function
37ab0 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 required. The f
37ac0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
37ad0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
37ae0 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 he.** required c
37af0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
37b00 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c e..**.** The cal
37b10 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 lback function s
37b20 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 hould register t
37b30 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 he desired colla
37b40 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
37b50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
37b60 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c llation()], [sql
37b70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
37b80 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a ation16()], or.*
37b90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
37ba0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
37bb0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
37bc0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 NTS:.**.** {H167
37bd0 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 02} A successful
37be0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
37bf0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
37c00 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 ed(D,P,F)].**
37c10 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 or [sqlit
37c20 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
37c30 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 ded16(D,P,F)] ca
37c40 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 uses.**
37c50 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
37c60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 onnection] D to
37c70 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 invoke callback
37c80 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 F with first.**
37c90 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 paramet
37ca0 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 er P whenever it
37cb0 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 needs a compari
37cc0 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 son function for
37cd0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 a.** c
37ce0 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 ollating sequenc
37cf0 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e e that it does n
37d00 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a ot know about..*
37d10 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 *.** {H16704} Ea
37d20 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 ch successful ca
37d30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
37d40 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
37d50 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 )] or.**
37d60 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 [sqlite3_colla
37d70 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d tion_needed16()]
37d80 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 63 overrides the c
37d90 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 allback register
37da0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ed.** o
37db0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 n the same [data
37dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
37dd0 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 by prior calls
37de0 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 to either.**
37df0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e interface.
37e00 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 .**.** {H16706}
37e10 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
37e20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 requested collat
37e30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 ing function pas
37e40 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 sed in the.**
37e50 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 4th param
37e60 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c eter to the call
37e70 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 back is in UTF-8
37e80 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b if the callback
37e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 .** was
37ea0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e registered usin
37eb0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 g [sqlite3_colla
37ec0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 tion_needed()] a
37ed0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 nd.** i
37ee0 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 s in UTF-16 nati
37ef0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 ve byte order if
37f00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 the callback wa
37f10 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 s.** re
37f20 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b gistered using [
37f30 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
37f40 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a n_needed16()]..*
37f50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
37f60 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a llation_needed(.
37f70 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
37f80 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 oid*, . void(*)
37f90 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
37fa0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e int eTextRep,con
37fb0 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 st char*).);.int
37fc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
37fd0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 on_needed16(. s
37fe0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
37ff0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 *,. void(*)(voi
38000 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
38010 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 eTextRep,const v
38020 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid*).);../*.**
38030 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 Specify the key
38040 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 for an encrypted
38050 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 database. This
38060 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 routine should
38070 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 be.** called rig
38080 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ht after sqlite3
38090 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 _open()..**.** T
380a0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 he code to imple
380b0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 ment this API is
380c0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 not available i
380d0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c n the public rel
380e0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ease.** of SQLit
380f0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
38100 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 3_key(. sqlite3
38110 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
38120 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
38130 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 ase to be rekeye
38140 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 d */. const voi
38150 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 d *pKey, int nKe
38160 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 y /* The key
38170 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 */.);../*.** Ch
38180 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 ange the key on
38190 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 an open database
381a0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e . If the curren
381b0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f t database is no
381c0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 t.** encrypted,
381d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c this routine wil
381e0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 l encrypt it. I
381f0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 f pNew==0 or nNe
38200 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 w==0, the.** dat
38210 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 abase is decrypt
38220 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ed..**.** The co
38230 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 de to implement
38240 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 this API is not
38250 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 available in the
38260 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a public release.
38270 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ** of SQLite..*/
38280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b .int sqlite3_rek
38290 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 ey(. sqlite3 *d
382a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
382b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
382c0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a to be rekeyed *
382d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
382e0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 pKey, int nKey
382f0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 /* The new ke
38300 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y */.);../*.** C
38310 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 API3REF: Suspend
38320 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 Execution For A
38330 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 Short Time {H10
38340 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 530} <S40410>.**
38350 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
38360 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e sleep() function
38370 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 causes the curr
38380 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 ent thread to su
38390 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a spend execution.
383a0 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 ** for at least
383b0 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c a number of mill
383c0 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 iseconds specifi
383d0 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 ed in its parame
383e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ter..**.** If th
383f0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
38400 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 em does not supp
38410 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 ort sleep reques
38420 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 ts with.** milli
38430 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f second time reso
38440 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 lution, then the
38450 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f time will be ro
38460 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 unded up to.** t
38470 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e he nearest secon
38480 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 d. The number of
38490 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
384a0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a sleep actually.
384b0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f ** requested fro
384c0 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 m the operating
384d0 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e system is return
384e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ed..**.** SQLite
384f0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 implements this
38500 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 interface by ca
38510 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 lling the xSleep
38520 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 ().** method of
38530 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
38540 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
38550 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
38560 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 TS:.**.** {H1053
38570 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
38580 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 sleep(M)] interf
38590 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ace invokes the
385a0 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 xSleep.**
385b0 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 method of the
385c0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
385d0 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 3_vfs|VFS] in or
385e0 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 der to.**
385f0 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 suspend execu
38600 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 tion of the curr
38610 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 ent thread for a
38620 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 t least.**
38630 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e M millisecon
38640 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 ds..**.** {H1053
38650 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
38660 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 sleep(M)] interf
38670 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
38680 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 number of.**
38690 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e millisecon
386a0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 ds of sleep actu
386b0 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f ally requested o
386c0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a f the operating.
386d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74 ** syst
386e0 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 em, which might
386f0 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
38700 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a he parameter M..
38710 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
38720 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a leep(int);../*.*
38730 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 * CAPI3REF: Name
38740 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 Of The Folder H
38750 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 olding Temporary
38760 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 Files {H10310}
38770 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 <S20000>.**.** I
38780 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 f this global va
38790 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 riable is made t
387a0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 o point to a str
387b0 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 ing which is.**
387c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f the name of a fo
387d0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 lder (a.k.a. dir
387e0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c ectory), then al
387f0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 l temporary file
38800 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 s.** created by
38810 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 SQLite will be p
38820 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 laced in that di
38830 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 rectory. If thi
38840 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 s variable.** is
38850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
38860 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 then SQLite per
38870 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 forms a search f
38880 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 or an appropriat
38890 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 e.** temporary f
388a0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a ile directory..*
388b0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 *.** It is not s
388c0 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 afe to modify th
388d0 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 is variable once
388e0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
388f0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 nection].** has
38900 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 been opened. It
38910 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 is intended tha
38920 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 t this variable
38930 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 be set once.** a
38940 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 s part of proces
38950 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
38960 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 and before any
38970 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
38980 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 .** routines hav
38990 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 e been call and
389a0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 remain unchanged
389b0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a thereafter..*/.
389c0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 SQLITE_EXTERN ch
389d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 ar *sqlite3_temp
389e0 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a _directory;../*.
389f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
38a00 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 t For Auto-Commi
38a10 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 t Mode {H12930}
38a20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S60200>.** KEYW
38a30 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 ORDS: {autocommi
38a40 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 t mode}.**.** Th
38a50 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 e sqlite3_get_au
38a60 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 tocommit() inter
38a70 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e face returns non
38a80 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f -zero or.** zero
38a90 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 if the given da
38aa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
38ab0 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 n is or is not i
38ac0 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 n autocommit mod
38ad0 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 e,.** respective
38ae0 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ly. Autocommit
38af0 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 mode is on by de
38b00 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f fault..** Autoco
38b10 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 mmit mode is dis
38b20 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 abled by a [BEGI
38b30 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a N] statement..**
38b40 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 Autocommit mode
38b50 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 is re-enabled b
38b60 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 y a [COMMIT] or
38b70 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a [ROLLBACK]..**.*
38b80 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e * If certain kin
38b90 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 ds of errors occ
38ba0 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e ur on a statemen
38bb0 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 t within a multi
38bc0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 -statement.** tr
38bd0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 ansaction (error
38be0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c s including [SQL
38bf0 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 ITE_FULL], [SQLI
38c00 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 TE_IOERR],.** [S
38c10 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 QLITE_NOMEM], [S
38c20 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 QLITE_BUSY], and
38c30 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
38c40 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a PT]) then the.**
38c50 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 transaction mig
38c60 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ht be rolled bac
38c70 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
38c80 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 The only way t
38c90 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 o.** find out wh
38ca0 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 ether SQLite aut
38cb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
38cc0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 d back the trans
38cd0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 action after.**
38ce0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 an error is to u
38cf0 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e se this function
38d00 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
38d10 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 TS:.**.** {H1293
38d20 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
38d30 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 get_autocommit(D
38d40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
38d50 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 urns non-zero or
38d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
38d70 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 o if the [databa
38d80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
38d90 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e is or is not in
38da0 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 autocommit.**
38db0 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 mode, re
38dc0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
38dd0 2a 20 7b 48 31 32 39 33 32 7d 20 41 75 74 6f 63 * {H12932} Autoc
38de0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e ommit mode is on
38df0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a by default..**.
38e00 2a 2a 20 7b 48 31 32 39 33 33 7d 20 41 75 74 6f ** {H12933} Auto
38e10 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 commit mode is d
38e20 69 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 isabled by a suc
38e30 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 cessful [BEGIN]
38e40 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
38e50 20 7b 48 31 32 39 33 34 7d 20 41 75 74 6f 63 6f {H12934} Autoco
38e60 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 mmit mode is ena
38e70 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 bled by a succes
38e80 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 sful [COMMIT] or
38e90 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 [ROLLBACK].**
38ea0 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e statemen
38eb0 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 t..**.** ASSUMPT
38ec0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 IONS:.**.** {A12
38ed0 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 936} If another
38ee0 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 thread changes t
38ef0 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 he autocommit st
38f00 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 atus of the data
38f10 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 base.**
38f20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
38f30 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 e this routine i
38f40 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 s running, then
38f50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
38f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
38f70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e undefined..*/.in
38f80 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 t sqlite3_get_au
38f90 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 tocommit(sqlite3
38fa0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
38fb0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 REF: Find The Da
38fc0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 tabase Handle Of
38fd0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
38fe0 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c ement {H13120} <
38ff0 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S60600>.**.** Th
39000 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e e sqlite3_db_han
39010 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 dle interface re
39020 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 turns the [datab
39030 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
39040 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 handle.** to whi
39050 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 ch a [prepared s
39060 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 tatement] belong
39070 73 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 s. The database
39080 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 handle returned
39090 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 by.** sqlite3_d
390a0 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 b_handle is the
390b0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 same database ha
390c0 6e 64 6c 65 20 74 68 61 74 20 77 61 73 20 74 68 ndle that was th
390d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
390e0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
390f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
39100 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 ] call (or its v
39110 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 ariants) that wa
39120 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 s used to.** cre
39130 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
39140 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 t in the first p
39150 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 lace..**.** INVA
39160 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
39170 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 13123} The [sqli
39180 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 te3_db_handle(S)
39190 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
391a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a rns a pointer.**
391b0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
391c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
391d0 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 ction] associate
391e0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 20 20 d with the.**
391f0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
39200 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
39210 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
39220 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c e3_db_handle(sql
39230 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
39240 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
39250 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 nd the next prep
39260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b ared statement {
39270 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e H13140} <S60600>
39280 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
39290 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
392a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e pointer to the n
392b0 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 ext [prepared st
392c0 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a atement] after.*
392d0 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 * pStmt associat
392e0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
392f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
39300 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 ] pDb. If pStmt
39310 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e is NULL.** then
39320 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
39330 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
39340 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 r to the first p
39350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
39360 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 t.** associated
39370 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 with the databas
39380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 e connection pDb
39390 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 . If no prepare
393a0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 d statement.** s
393b0 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e atisfies the con
393c0 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 ditions of this
393d0 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 routine, it retu
393e0 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 rns NULL..**.**
393f0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
39400 2a 20 7b 48 31 33 31 34 33 7d 20 49 66 20 44 20 * {H13143} If D
39410 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
39420 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 onnection] that
39430 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 holds one or mor
39440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e e.** un
39450 66 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 finalized [prepa
39460 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
39470 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 and S is a NULL
39480 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 pointer,.**
39490 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 then [sqlit
394a0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 e3_next_stmt(D,
394b0 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c S)] routine shal
394c0 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 l return a point
394d0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 er.** t
394e0 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 72 65 o one of the pre
394f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
39500 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
39510 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 D..**.** {H1314
39520 36 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 6} If D is a [da
39530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
39540 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f n] that holds no
39550 20 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 unfinalized.**
39560 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 [prepar
39570 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 ed statements] a
39580 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 nd S is a NULL p
39590 6f 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 ointer, then.**
395a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
395b0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 3_next_stmt(D, S
395c0 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c )] routine shall
395d0 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 return a NULL p
395e0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ointer..**.** {H
395f0 31 33 31 34 39 7d 20 49 66 20 53 20 69 73 20 61 13149} If S is a
39600 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
39610 6d 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64 61 ment] in the [da
39620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
39630 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 n] D.**
39640 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68 and S is not th
39650 65 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 e last prepared
39660 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20 statement in D,
39670 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 then.**
39680 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
39690 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 tmt(D, S)] routi
396a0 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 ne shall return
396b0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 a pointer.**
396c0 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65 78 to the nex
396d0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 t prepared state
396e0 6d 65 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20 ment in D after
396f0 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 S..**.** {H13152
39700 7d 20 49 66 20 53 20 69 73 20 74 68 65 20 6c 61 } If S is the la
39710 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 st [prepared sta
39720 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a tement] in the.*
39730 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 * [data
39740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
39750 20 44 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c D then the [sql
39760 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 ite3_next_stmt(D
39770 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 , S)].**
39780 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 routine shall
39790 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f return a NULL po
397a0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 inter..**.** ASS
397b0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
397c0 7b 41 31 33 31 35 34 7d 20 54 68 65 20 5b 64 61 {A13154} The [da
397d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
397e0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 n] pointer D in
397f0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 a call to.**
39800 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e [sqlite3_n
39810 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d ext_stmt(D,S)] m
39820 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 ust refer to an
39830 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a open database.**
39840 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 connec
39850 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 tion and in part
39860 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 icular must not
39870 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
39880 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 r..*/.sqlite3_st
39890 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 mt *sqlite3_next
398a0 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 _stmt(sqlite3 *p
398b0 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 Db, sqlite3_stmt
398c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
398d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 CAPI3REF: Commi
398e0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e t And Rollback N
398f0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c otification Call
39900 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c backs {H12950} <
39910 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S60400>.**.** Th
39920 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 e sqlite3_commit
39930 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 _hook() interfac
39940 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
39950 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
39960 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 on to be invoked
39970 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e whenever a tran
39980 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 saction is commi
39990 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c tted..** Any cal
399a0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 lback set by a p
399b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
399c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
399d0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
399e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
399f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
39a00 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 rridden..** The
39a10 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b sqlite3_rollback
39a20 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 _hook() interfac
39a30 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
39a40 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
39a50 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 on to be invoked
39a60 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e whenever a tran
39a70 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 saction is commi
39a80 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c tted..** Any cal
39a90 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 lback set by a p
39aa0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
39ab0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
39ac0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
39ad0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
39ae0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
39af0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 rridden..** The
39b00 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 pArg argument is
39b10 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
39b20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e to the callback.
39b30 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 .** If the callb
39b40 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 ack on a commit
39b50 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 hook function re
39b60 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a turns non-zero,.
39b70 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d ** then the comm
39b80 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 it is converted
39b90 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e into a rollback.
39ba0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
39bb0 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 r function was p
39bc0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
39bd0 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 ered, its.** pAr
39be0 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 g value is retur
39bf0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
39c00 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
39c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
39c20 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 back implementat
39c30 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ion must not do
39c40 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
39c50 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
39c60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
39c70 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
39c80 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 d the callback.
39c90 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 Any actions.**
39ca0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 to modify the da
39cb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
39cc0 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 n must be deferr
39cd0 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 ed until after t
39ce0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e he.** completion
39cf0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
39d00 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 _step()] call th
39d10 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
39d20 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f commit.** or ro
39d30 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 llback hook in t
39d40 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a he first place..
39d50 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
39d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
39d70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
39d80 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
39d90 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
39da0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
39db0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
39dc0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
39dd0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
39de0 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
39df0 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 ing a NULL funct
39e00 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 ion disables the
39e10 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
39e20 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 For the purpose
39e30 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 s of this API, a
39e40 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
39e50 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 said to have bee
39e60 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b n.** rolled back
39e70 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 if an explicit
39e80 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 "ROLLBACK" state
39e90 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 ment is executed
39ea0 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 , or.** an error
39eb0 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 or constraint c
39ec0 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 auses an implici
39ed0 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 t rollback to oc
39ee0 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c cur..** The roll
39ef0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 back callback is
39f00 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 not invoked if
39f10 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
39f20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
39f30 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 y rolled back be
39f40 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 cause the databa
39f50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
39f60 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 closed..** The
39f70 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 rollback callbac
39f80 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
39f90 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f if a transactio
39fa0 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 n is.** rolled b
39fb0 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f ack because a co
39fc0 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 mmit callback re
39fd0 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e turned non-zero.
39fe0 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b .** <todo> Check
39ff0 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e on this </todo>
3a000 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
3a010 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 S:.**.** {H12951
3a020 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
3a030 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 ommit_hook(D,F,P
3a040 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 )] interface reg
3a050 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 isters the.**
3a060 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 callback
3a070 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 function F to be
3a080 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 invoked with ar
3a090 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 gument P wheneve
3a0a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 r.** a
3a0b0 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d transaction comm
3a0c0 69 74 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 its on the [data
3a0d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3a0e0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 D..**.** {H1295
3a0f0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
3a100 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c commit_hook(D,F,
3a110 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 P)] interface re
3a120 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 turns the P argu
3a130 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 ment.**
3a140 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f from the previo
3a150 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 us call with the
3a160 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
3a170 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a connection] D,.*
3a180 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 * or NU
3a190 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 LL on the first
3a1a0 63 61 6c 6c 20 66 6f 72 20 61 20 70 61 72 74 69 call for a parti
3a1b0 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 cular database c
3a1c0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a onnection D..**.
3a1d0 2a 2a 20 7b 48 31 32 39 35 33 7d 20 45 61 63 68 ** {H12953} Each
3a1e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
3a1f0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 3_commit_hook()]
3a200 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 overwrites the
3a210 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 callback.**
3a220 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 registered
3a230 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a by prior calls..
3a240 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 34 7d 20 49 **.** {H12954} I
3a250 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 f the F argument
3a260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
3a270 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d mit_hook(D,F,P)]
3a280 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 is NULL.**
3a290 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f then the co
3a2a0 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 mmit hook callba
3a2b0 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 ck is canceled a
3a2c0 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a nd no callback.*
3a2d0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e * is in
3a2e0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 voked when a tra
3a2f0 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 nsaction commits
3a300 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 35 7d ..**.** {H12955}
3a310 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 If the commit c
3a320 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
3a330 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 non-zero then th
3a340 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 e commit is.**
3a350 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 converte
3a360 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 d into a rollbac
3a370 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 k..**.** {H12961
3a380 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
3a390 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 ollback_hook(D,F
3a3a0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,P)] interface r
3a3b0 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 egisters the.**
3a3c0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 callbac
3a3d0 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 k function F to
3a3e0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
3a3f0 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 argument P whene
3a400 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ver.**
3a410 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f a transaction ro
3a420 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 lls back on the
3a430 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3a440 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b tion] D..**.** {
3a450 48 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c H12962} The [sql
3a460 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
3a470 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 ok(D,F,P)] inter
3a480 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
3a490 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 P.** a
3a4a0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 rgument from the
3a4b0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 previous call w
3a4c0 69 74 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 ith the same.**
3a4d0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
3a4e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
3a4f0 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 , or NULL on the
3a500 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 first call.**
3a510 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 for a pa
3a520 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
3a530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a e connection D..
3a540 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 33 7d 20 45 **.** {H12963} E
3a550 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ach call to [sql
3a560 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
3a570 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 ok()] overwrites
3a580 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a the callback.**
3a590 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 regist
3a5a0 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 ered by prior ca
3a5b0 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 lls..**.** {H129
3a5c0 36 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 64} If the F arg
3a5d0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
3a5e0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
3a5f0 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a D,F,P)] is NULL.
3a600 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
3a610 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f the rollback ho
3a620 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 ok callback is c
3a630 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 anceled and no c
3a640 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 allback.**
3a650 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 is invoked w
3a660 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f hen a transactio
3a670 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f n rolls back..*/
3a680 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 .void *sqlite3_c
3a690 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 ommit_hook(sqlit
3a6a0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
3a6b0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 *), void*);.void
3a6c0 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 *sqlite3_rollba
3a6d0 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a ck_hook(sqlite3*
3a6e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a , void(*)(void *
3a6f0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
3a700 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
3a710 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 Change Notifica
3a720 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b tion Callbacks {
3a730 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e H12970} <S60400>
3a740 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
3a750 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 e3_update_hook()
3a760 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
3a770 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
3a780 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 function.** with
3a790 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
3a7a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 onnection] ident
3a7b0 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 ified by the fir
3a7c0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 st argument.** t
3a7d0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
3a7e0 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 never a row is u
3a7f0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 pdated, inserted
3a800 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 or deleted..**
3a810 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 Any callback set
3a820 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 by a previous c
3a830 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 all to this func
3a840 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 tion.** for the
3a850 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
3a860 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 nnection is over
3a870 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 ridden..**.** Th
3a880 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
3a890 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
3a8a0 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 o the function t
3a8b0 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a o invoke when a.
3a8c0 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 ** row is update
3a8d0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 d, inserted or d
3a8e0 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 eleted..** The f
3a8f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
3a900 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
3a910 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 a copy of the t
3a920 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a hird argument.**
3a930 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 to sqlite3_upda
3a940 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 te_hook()..** Th
3a950 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 e second callbac
3a960 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e k argument is on
3a970 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 e of [SQLITE_INS
3a980 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 ERT], [SQLITE_DE
3a990 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 LETE],.** or [SQ
3a9a0 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 LITE_UPDATE], de
3a9b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
3a9c0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 peration that ca
3a9d0 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 used the callbac
3a9e0 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b k.** to be invok
3a9f0 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 ed..** The third
3aa00 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 and fourth argu
3aa10 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c ments to the cal
3aa20 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f lback contain po
3aa30 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a inters to the.**
3aa40 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 database and ta
3aa50 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e ble name contain
3aa60 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 ing the affected
3aa70 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e row..** The fin
3aa80 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 al callback para
3aa90 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 meter is the row
3aaa0 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 id of the row. I
3aab0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 0a 2a 2a n the case of.**
3aac0 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 an update, this
3aad0 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 is the rowid af
3aae0 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 ter the update t
3aaf0 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a akes place..**.*
3ab00 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f * The update hoo
3ab10 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
3ab20 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 when internal s
3ab30 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 ystem tables are
3ab40 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e .** modified (i.
3ab50 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 e. sqlite_master
3ab60 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 and sqlite_sequ
3ab70 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ence)..**.** The
3ab80 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 update hook imp
3ab90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 lementation must
3aba0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
3abb0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
3abc0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
3abd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
3abe0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 t invoked the up
3abf0 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 date hook. Any
3ac00 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f actions.** to mo
3ac10 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 dify the databas
3ac20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 e connection mus
3ac30 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e t be deferred un
3ac40 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a til after the.**
3ac50 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 completion of t
3ac60 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
3ac70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ()] call that tr
3ac80 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 iggered the upda
3ac90 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 te hook..** Note
3aca0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
3acb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
3acc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
3acd0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
3ace0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
3acf0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
3ad00 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
3ad10 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
3ad20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
3ad30 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
3ad40 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
3ad50 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
3ad60 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a its pArg value.*
3ad70 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 * is returned.
3ad80 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 Otherwise NULL i
3ad90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
3ada0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
3adb0 0a 2a 2a 20 7b 48 31 32 39 37 31 7d 20 54 68 65 .** {H12971} The
3adc0 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 [sqlite3_update
3add0 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e _hook(D,F,P)] in
3ade0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
3adf0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 he callback.**
3ae00 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e function
3ae10 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 F to be invoked
3ae20 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61 with first para
3ae30 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 meter P whenever
3ae40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 .** a t
3ae50 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 able row is modi
3ae60 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 fied, inserted,
3ae70 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a or deleted on.**
3ae80 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 the [d
3ae90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3aea0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 on] D..**.** {H1
3aeb0 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 2973} The [sqlit
3aec0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 e3_update_hook(D
3aed0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
3aee0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c returns the val
3aef0 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ue.** o
3af00 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 f P for the prev
3af10 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 ious call on the
3af20 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
3af30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a connection] D,.*
3af40 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 * or NU
3af50 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 LL for the first
3af60 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 call..**.** {H1
3af70 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 2975} If the upd
3af80 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 ate hook callbac
3af90 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f k F in [sqlite3_
3afa0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c update_hook(D,F,
3afb0 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 P)].**
3afc0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
3afd0 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 no update callb
3afe0 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a acks are made..*
3aff0 2a 0a 2a 2a 20 7b 48 31 32 39 37 37 7d 20 45 61 *.** {H12977} Ea
3b000 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
3b010 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
3b020 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 D,F,P)] override
3b030 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a s prior calls.**
3b040 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
3b050 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 same interface
3b060 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 on the same [dat
3b070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3b080 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ] D..**.** {H129
3b090 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 79} The update h
3b0a0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ook callback is
3b0b0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
3b0c0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d internal system
3b0d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 .** tab
3b0e0 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 les such as sqli
3b0f0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 te_master and sq
3b100 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 lite_sequence ar
3b110 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a e modified..**.*
3b120 2a 20 7b 48 31 32 39 38 31 7d 20 54 68 65 20 73 * {H12981} The s
3b130 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
3b140 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61 to the update ca
3b150 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 llback.**
3b160 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 is one of [SQ
3b170 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 LITE_INSERT], [S
3b180 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 QLITE_DELETE] or
3b190 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d [SQLITE_UPDATE]
3b1a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 ,.** de
3b1b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
3b1c0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 peration that ca
3b1d0 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 used the callbac
3b1e0 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e k to be invoked.
3b1f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 33 7d 20 .**.** {H12983}
3b200 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
3b210 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 urth arguments t
3b220 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 o the callback c
3b230 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a ontain pointers.
3b240 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a ** to z
3b250 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
3b260 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 TF-8 strings whi
3b270 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 ch are the names
3b280 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
3b290 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 database and
3b2a0 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 table that is b
3b2b0 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a eing updated...*
3b2c0 2a 20 7b 48 31 32 39 38 35 7d 20 54 68 65 20 66 * {H12985} The f
3b2d0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 inal callback pa
3b2e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 rameter is the r
3b2f0 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 owid of the row
3b300 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 after.**
3b310 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63 the change occ
3b320 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 urs..*/.void *sq
3b330 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
3b340 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a k(. sqlite3*, .
3b350 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a void(*)(void *
3b360 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 ,int ,char const
3b370 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c *,char const *,
3b380 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a sqlite3_int64),.
3b390 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a void*.);../*.*
3b3a0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
3b3b0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 le Or Disable Sh
3b3c0 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 ared Pager Cache
3b3d0 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 {H10330} <S3090
3b3e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
3b3f0 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 20 7b {shared cache} {
3b400 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 shared cache mod
3b410 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f e}.**.** This ro
3b420 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 utine enables or
3b430 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 disables the sh
3b440 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 aring of the dat
3b450 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 abase cache.** a
3b460 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 nd schema data s
3b470 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 tructures betwee
3b480 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
3b490 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 ection | connect
3b4a0 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 ions].** to the
3b4b0 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 same database. S
3b4c0 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 haring is enable
3b4d0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e d if the argumen
3b4e0 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 t is true.** and
3b4f0 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 disabled if the
3b500 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c argument is fal
3b510 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 se..**.** Cache
3b520 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c sharing is enabl
3b530 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 ed and disabled
3b540 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 for an entire pr
3b550 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 ocess. {END}.**
3b560 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 This is a change
3b570 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 as of SQLite ve
3b580 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 rsion 3.5.0. In
3b590 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f prior versions o
3b5a0 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 f SQLite,.** sha
3b5b0 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 ring was enabled
3b5c0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 or disabled for
3b5d0 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 each thread sep
3b5e0 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 arately..**.** T
3b5f0 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 he cache sharing
3b600 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 mode set by thi
3b610 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 s interface effe
3b620 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 cts all subseque
3b630 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b nt.** calls to [
3b640 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
3b650 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
3b660 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 2()], and [sqlit
3b670 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a e3_open16()]..**
3b680 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 Existing databa
3b690 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 se connections c
3b6a0 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 ontinue use the
3b6b0 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 sharing mode.**
3b6c0 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 that was in effe
3b6d0 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 ct at the time t
3b6e0 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e hey were opened.
3b6f0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 .**.** Virtual t
3b700 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 ables cannot be
3b710 75 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 used with a shar
3b720 65 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 ed cache. When
3b730 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 shared.** cache
3b740 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 is enabled, the
3b750 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
3b760 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 module()] API us
3b770 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a ed to register.*
3b780 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * virtual tables
3b790 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
3b7a0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a urn an error..**
3b7b0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
3b7c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
3b7d0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 _OK] if shared c
3b7e0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 ache was enabled
3b7f0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
3b800 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 successfully. A
3b810 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
3b820 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 s returned other
3b830 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 wise..**.** Shar
3b840 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 ed cache is disa
3b850 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
3b860 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 But this might
3b870 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 change in.** fut
3b880 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
3b890 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 SQLite. Applica
3b8a0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 tions that care
3b8b0 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 about shared.**
3b8c0 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 cache setting sh
3b8d0 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c ould set it expl
3b8e0 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e icitly..**.** IN
3b8f0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
3b900 7b 48 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 {H10331} A succe
3b910 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
3b920 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 of [sqlite3_ena
3b930 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 ble_shared_cache
3b940 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 (B)].**
3b950 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 will enable or
3b960 64 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 disable shared c
3b970 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e ache mode for an
3b980 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a y subsequently.*
3b990 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74 * creat
3b9a0 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ed [database con
3b9b0 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 nection] in the
3b9c0 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a same process..**
3b9d0 0a 2a 2a 20 7b 48 31 30 33 33 36 7d 20 57 68 65 .** {H10336} Whe
3b9e0 6e 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 n shared cache i
3b9f0 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b s enabled, the [
3ba00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
3ba10 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 odule()].**
3ba20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 interface w
3ba30 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 ill always retur
3ba40 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a n an error..**.*
3ba50 2a 20 7b 48 31 30 33 33 37 7d 20 54 68 65 20 5b * {H10337} The [
3ba60 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 sqlite3_enable_s
3ba70 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 hared_cache(B)]
3ba80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
3ba90 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 s.** [S
3baa0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 QLITE_OK] if sha
3bab0 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e red cache was en
3bac0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
3bad0 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a d successfully..
3bae0 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 39 7d 20 53 **.** {H10339} S
3baf0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 hared cache is d
3bb00 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
3bb10 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 lt..*/.int sqlit
3bb20 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
3bb30 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a _cache(int);../*
3bb40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 .** CAPI3REF: At
3bb50 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 tempt To Free He
3bb60 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 ap Memory {H1734
3bb70 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 0} <S30220>.**.*
3bb80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
3bb90 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 lease_memory() i
3bba0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
3bbb0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 s to free N byte
3bbc0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d s.** of heap mem
3bbd0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 ory by deallocat
3bbe0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 ing non-essentia
3bbf0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
3bc00 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 ions.** held by
3bc10 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 the database lib
3bc20 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d rary. {END} Mem
3bc30 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 ory used to cach
3bc40 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 e database.** pa
3bc50 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 ges to improve p
3bc60 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e erformance is an
3bc70 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d example of non-
3bc80 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 essential memory
3bc90 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c ..** sqlite3_rel
3bca0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 ease_memory() re
3bcb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
3bcc0 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c of bytes actual
3bcd0 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 ly freed,.** whi
3bce0 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 ch might be more
3bcf0 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 or less than th
3bd00 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 e amount request
3bd10 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
3bd20 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ANTS:.**.** {H17
3bd30 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 341} The [sqlite
3bd40 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
3bd50 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 (N)] interface a
3bd60 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 ttempts to.**
3bd70 20 20 20 20 20 20 20 66 72 65 65 20 4e 20 62 79 free N by
3bd80 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f tes of heap memo
3bd90 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 ry by deallocati
3bda0 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c ng non-essential
3bdb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d .** mem
3bdc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ory allocations
3bdd0 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 held by the data
3bde0 62 61 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a base library..**
3bdf0 0a 2a 2a 20 7b 48 31 36 33 34 32 7d 20 54 68 65 .** {H16342} The
3be00 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
3be10 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 e_memory(N)] ret
3be20 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a urns the number.
3be30 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 ** of b
3be40 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 ytes actually fr
3be50 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 eed, which might
3be60 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 be more or less
3be70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 .** tha
3be80 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 n the amount req
3be90 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 uested..*/.int s
3bea0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
3beb0 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a emory(int);../*.
3bec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 ** CAPI3REF: Imp
3bed0 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 ose A Limit On H
3bee0 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 eap Size {H17350
3bef0 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a } <S30220>.**.**
3bf00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 The sqlite3_sof
3bf10 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 t_heap_limit() i
3bf20 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 nterface places
3bf30 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a a "soft" limit.*
3bf40 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 * on the amount
3bf50 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 of heap memory t
3bf60 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 hat may be alloc
3bf70 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a ated by SQLite..
3bf80 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 ** If an interna
3bf90 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 l allocation is
3bfa0 72 65 71 75 65 73 74 65 64 20 74 68 61 74 20 77 requested that w
3bfb0 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a ould exceed the.
3bfc0 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d ** soft heap lim
3bfd0 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c it, [sqlite3_rel
3bfe0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 ease_memory()] i
3bff0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 s invoked one or
3c000 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 .** more times t
3c010 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 o free up some s
3c020 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 pace before the
3c030 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 allocation is pe
3c040 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 rformed..**.** T
3c050 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c he limit is call
3c060 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 ed "soft", becau
3c070 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 se if [sqlite3_r
3c080 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d elease_memory()]
3c090 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 .** cannot free
3c0a0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 sufficient memor
3c0b0 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 y to prevent the
3c0c0 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e limit from bein
3c0d0 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 g exceeded,.** t
3c0e0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c he memory is all
3c0f0 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e ocated anyway an
3c100 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 d the current op
3c110 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
3c120 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 ..**.** A negati
3c130 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 ve or zero value
3c140 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 for N means tha
3c150 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f t there is no so
3c160 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e ft heap limit an
3c170 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 d.** [sqlite3_re
3c180 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 lease_memory()]
3c190 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c will only be cal
3c1a0 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 led when memory
3c1b0 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a is exhausted..**
3c1c0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c The default val
3c1d0 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 ue for the soft
3c1e0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 heap limit is ze
3c1f0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ro..**.** SQLite
3c200 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 makes a best ef
3c210 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 fort to honor th
3c220 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
3c230 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 t..** But if the
3c240 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
3c250 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 cannot be honor
3c260 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 ed, execution wi
3c270 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 ll.** continue w
3c280 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 ithout error or
3c290 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 notification. T
3c2a0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c his is why the l
3c2b0 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 imit is.** calle
3c2c0 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 d a "soft" limit
3c2d0 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 . It is advisor
3c2e0 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 y only..**.** Pr
3c2f0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
3c300 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 rsion 3.5.0, thi
3c310 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 s routine only c
3c320 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d onstrained the m
3c330 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
3c340 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 ed by a single t
3c350 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 hread - the same
3c360 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
3c370 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a this routine.**
3c380 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e runs. Beginnin
3c390 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 g with SQLite ve
3c3a0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 rsion 3.5.0, the
3c3b0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
3c3c0 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 is.** applied t
3c3d0 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 o all threads. T
3c3e0 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 he value specifi
3c3f0 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 ed for the soft
3c400 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 heap limit.** is
3c410 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 an upper bound
3c420 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d on the total mem
3c430 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
3c440 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 or all threads.
3c450 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e In.** version 3.
3c460 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 5.0 there is no
3c470 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 mechanism for li
3c480 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 miting the heap
3c490 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 usage for.** ind
3c4a0 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e ividual threads.
3c4b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
3c4c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 31 S:.**.** {H16351
3c4d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 } The [sqlite3_s
3c4e0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e oft_heap_limit(N
3c4f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 )] interface pla
3c500 63 65 73 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 ces a soft limit
3c510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 .** of
3c520 4e 20 62 79 74 65 73 20 6f 6e 20 74 68 65 20 61 N bytes on the a
3c530 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 mount of heap me
3c540 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 mory that may be
3c550 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 allocated.**
3c560 20 20 20 20 20 20 20 75 73 69 6e 67 20 5b 73 71 using [sq
3c570 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
3c580 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
3c590 6c 6f 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f loc()] at any po
3c5a0 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 int.**
3c5b0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b in time..**.** {
3c5c0 48 31 36 33 35 32 7d 20 49 66 20 61 20 63 61 6c H16352} If a cal
3c5d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 l to [sqlite3_ma
3c5e0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 lloc()] or [sqli
3c5f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 te3_realloc()] w
3c600 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ould.**
3c610 20 63 61 75 73 65 20 74 68 65 20 74 6f 74 61 6c cause the total
3c620 20 61 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 amount of alloc
3c630 61 74 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 ated memory to e
3c640 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 xceed the.**
3c650 20 20 20 20 20 20 73 6f 66 74 20 68 65 61 70 20 soft heap
3c660 6c 69 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c limit, then [sql
3c670 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
3c680 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 ory()] is invoke
3c690 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e d.** in
3c6a0 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 an attempt to r
3c6b0 65 64 75 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 educe the memory
3c6c0 20 75 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20 usage prior to
3c6d0 70 72 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 proceeding.**
3c6e0 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 with the
3c6f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
3c700 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a n attempt..**.**
3c710 20 7b 48 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 {H16353} Calls
3c720 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
3c730 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
3c740 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 3_realloc()] tha
3c750 74 20 74 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 t trigger.**
3c760 20 20 20 20 20 20 61 74 74 65 6d 70 74 73 20 74 attempts t
3c770 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 o reduce memory
3c780 75 73 61 67 65 20 74 68 72 6f 75 67 68 20 74 68 usage through th
3c790 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
3c7a0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 t.** me
3c7b0 63 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 chanism continue
3c7c0 20 65 76 65 6e 20 69 66 20 74 68 65 20 61 74 74 even if the att
3c7d0 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 6d empt to reduce m
3c7e0 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 emory.**
3c7f0 20 20 75 73 61 67 65 20 69 73 20 75 6e 73 75 63 usage is unsuc
3c800 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b cessful..**.** {
3c810 48 31 36 33 35 34 7d 20 41 20 6e 65 67 61 74 69 H16354} A negati
3c820 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 ve or zero value
3c830 20 66 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c for N in a call
3c840 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
3c850 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 [sqlite3_soft_he
3c860 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 ap_limit(N)] mea
3c870 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 ns that there is
3c880 20 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 no soft.**
3c890 20 20 20 20 20 68 65 61 70 20 6c 69 6d 69 74 20 heap limit
3c8a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c and [sqlite3_rel
3c8b0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 ease_memory()] w
3c8c0 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 ill only be.**
3c8d0 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 77 called w
3c8e0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f hen memory is co
3c8f0 6d 70 6c 65 74 65 6c 79 20 65 78 68 61 75 73 74 mpletely exhaust
3c900 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 ed..**.** {H1635
3c910 35 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 5} The default v
3c920 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 alue for the sof
3c930 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
3c940 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 zero..**.** {H16
3c950 33 35 38 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 358} Each call t
3c960 6f 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f o [sqlite3_soft_
3c970 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f heap_limit(N)] o
3c980 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 verrides the.**
3c990 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 values
3c9a0 73 65 74 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 set by all prior
3c9b0 20 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 calls..*/.void
3c9c0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
3c9d0 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f p_limit(int);../
3c9e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
3c9f0 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 xtract Metadata
3ca00 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f About A Column O
3ca10 66 20 41 20 54 61 62 6c 65 20 7b 48 31 32 38 35 f A Table {H1285
3ca20 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S60300>.**.*
3ca30 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
3ca40 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 eturns metadata
3ca50 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 about a specific
3ca60 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 column of a spe
3ca70 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 cific.** databas
3ca80 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 e table accessib
3ca90 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 le using the [da
3caa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3cab0 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 n] handle.** pas
3cac0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
3cad0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
3cae0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f nt..**.** The co
3caf0 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 lumn is identifi
3cb00 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
3cb10 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 , third and four
3cb20 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
3cb30 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f .** this functio
3cb40 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 n. The second pa
3cb50 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 rameter is eithe
3cb60 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 r the name of th
3cb70 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 e database.** (i
3cb80 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d .e. "main", "tem
3cb90 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 p" or an attache
3cba0 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 d database) cont
3cbb0 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 aining the speci
3cbc0 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 fied.** table or
3cbd0 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 NULL. If it is
3cbe0 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 NULL, then all a
3cbf0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
3cc00 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a s are searched.*
3cc10 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 * for the table
3cc20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 using the same a
3cc30 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 lgorithm used by
3cc40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
3cc50 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c gine to.** resol
3cc60 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 ve unqualified t
3cc70 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e able references.
3cc80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 .**.** The third
3cc90 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 and fourth para
3cca0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 meters to this f
3ccb0 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 unction are the
3ccc0 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e table and column
3ccd0 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 .** name of the
3cce0 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 desired column,
3ccf0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 respectively. Ne
3cd00 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 ither of these p
3cd10 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 arameters.** may
3cd20 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
3cd30 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 Metadata is retu
3cd40 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 rned by writing
3cd50 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f to the memory lo
3cd60 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 cations passed a
3cd70 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 s the 5th.** and
3cd80 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 subsequent para
3cd90 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 meters to this f
3cda0 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 unction. Any of
3cdb0 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 these arguments
3cdc0 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 may be.** NULL,
3cdd0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 in which case th
3cde0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
3cdf0 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 element of metad
3ce00 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a ata is omitted..
3ce10 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
3ce20 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 e>.** <table bor
3ce30 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e der="1">.** <tr>
3ce40 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c <th> Parameter <
3ce50 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 th> Output<br>Ty
3ce60 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 pe <th> Descrip
3ce70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c tion.**.** <tr><
3ce80 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e td> 5th <td> con
3ce90 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 st char* <td> Da
3cea0 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c ta type.** <tr><
3ceb0 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e td> 6th <td> con
3cec0 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 st char* <td> Na
3ced0 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f me of default co
3cee0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
3cef0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 .** <tr><td> 7th
3cf00 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 <td> int
3cf10 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 <td> True if c
3cf20 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 olumn has a NOT
3cf30 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a NULL constraint.
3cf40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 ** <tr><td> 8th
3cf50 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 <td> int
3cf60 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f <td> True if co
3cf70 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 lumn is part of
3cf80 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a the PRIMARY KEY.
3cf90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 ** <tr><td> 9th
3cfa0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 <td> int
3cfb0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f <td> True if co
3cfc0 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 lumn is AUTOINCR
3cfd0 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 74 61 62 6c 65 EMENT.** </table
3cfe0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
3cff0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d e>.**.** The mem
3d000 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ory pointed to b
3d010 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 y the character
3d020 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
3d030 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 d for the.** dec
3d040 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e laration type an
3d050 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
3d060 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e ence is valid on
3d070 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 ly until the nex
3d080 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 t.** call to any
3d090 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 SQLite API func
3d0a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 tion..**.** If t
3d0b0 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 he specified tab
3d0c0 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 le is actually a
3d0d0 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 view, an [error
3d0e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
3d0f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
3d100 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d specified colum
3d110 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f n is "rowid", "o
3d120 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 id" or "_rowid_"
3d130 20 61 6e 64 20 61 6e 0a 2a 2a 20 49 4e 54 45 47 and an.** INTEG
3d140 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 ER PRIMARY KEY c
3d150 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 olumn has been e
3d160 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
3d170 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 ed, then the out
3d180 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 put.** parameter
3d190 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 s are set for th
3d1a0 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 e explicitly dec
3d1b0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 lared column. If
3d1c0 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 there is no.**
3d1d0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
3d1e0 72 65 64 20 49 4e 54 45 47 45 52 20 50 52 49 4d red INTEGER PRIM
3d1f0 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 2c 20 ARY KEY column,
3d200 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a then the output.
3d210 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 ** parameters ar
3d220 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 e set as follows
3d230 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a :.**.** <pre>.**
3d240 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 data type:
3d250 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 "INTEGER".**
3d260 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
3d270 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a nce: "BINARY".**
3d280 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 not null: 0
3d290 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 .** primary
3d2a0 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 key: 1.** au
3d2b0 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a to increment: 0.
3d2c0 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 ** </pre>.**.**
3d2d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 This function ma
3d2e0 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f y load one or mo
3d2f0 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 re schemas from
3d300 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 database files.
3d310 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f If an.** error o
3d320 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 ccurs during thi
3d330 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 s process, or if
3d340 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 the requested t
3d350 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a able or column.*
3d360 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e * cannot be foun
3d370 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 d, an [error cod
3d380 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 e] is returned a
3d390 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 nd an error mess
3d3a0 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 age left.** in t
3d3b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
3d3c0 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 nection] (to be
3d3d0 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 retrieved using
3d3e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
3d3f0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 )..**.** This AP
3d400 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 I is only availa
3d410 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
3d420 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
3d430 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
3d440 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d ITE_ENABLE_COLUM
3d450 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 N_METADATA] C-pr
3d460 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f eprocessor symbo
3d470 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e l defined..*/.in
3d480 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f t sqlite3_table_
3d490 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 column_metadata(
3d4a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
3d4b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3d4c0 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e * Connection han
3d4d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
3d4e0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 har *zDbName,
3d4f0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
3d500 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f name or NULL */
3d510 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
3d520 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f TableName, /
3d530 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a * Table name */.
3d540 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
3d550 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a olumnName, /*
3d560 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a Column name */.
3d570 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 char const **p
3d580 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a zDataType, /*
3d590 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 OUTPUT: Declare
3d5a0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 d data type */.
3d5b0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a char const **pz
3d5c0 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 CollSeq, /*
3d5d0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f OUTPUT: Collatio
3d5e0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 n sequence name
3d5f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 */. int *pNotNu
3d600 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ll,
3d610 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
3d620 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e if NOT NULL con
3d630 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a straint exists *
3d640 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 /. int *pPrimar
3d650 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 yKey,
3d660 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 /* OUTPUT: True
3d670 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f if column part o
3d680 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 f PK */. int *p
3d690 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 Autoinc
3d6a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
3d6b0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
3d6c0 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e is auto-incremen
3d6d0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t */.);../*.** C
3d6e0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e API3REF: Load An
3d6f0 20 45 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 Extension {H126
3d700 30 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 00} <S20500>.**.
3d710 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
3d720 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 e loads an SQLit
3d730 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 e extension libr
3d740 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d ary from the nam
3d750 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b ed file..**.** {
3d760 48 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 H12601} The sqli
3d770 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
3d780 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 on() interface a
3d790 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 ttempts to load
3d7a0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 an.** S
3d7b0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 QLite extension
3d7c0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 library containe
3d7d0 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 d in the file zF
3d7e0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ile..**.** {H126
3d7f0 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 02} The entry po
3d800 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a int is zProc..**
3d810 0a 2a 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 .** {H12603} zPr
3d820 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 oc may be 0, in
3d830 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e which case the n
3d840 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 ame of the entry
3d850 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 point.**
3d860 20 20 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 defaults to "
3d870 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f sqlite3_extensio
3d880 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b n_init"..**.** {
3d890 48 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 H12604} The sqli
3d8a0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
3d8b0 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 on() interface s
3d8c0 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 hall return.**
3d8d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
3d8e0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
3d8f0 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 nd [SQLITE_ERROR
3d900 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 ] if something g
3d910 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a oes wrong..**.**
3d920 20 7b 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 {H12605} If an
3d930 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 error occurs and
3d940 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 pzErrMsg is not
3d950 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 0, then the.**
3d960 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3d970 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
3d980 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 ()] interface sh
3d990 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a all attempt to.*
3d9a0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 * fill
3d9b0 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 *pzErrMsg with e
3d9c0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 rror message tex
3d9d0 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f t stored in memo
3d9e0 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ry.** o
3d9f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
3da00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
3da10 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c {END} The call
3da20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ing function.**
3da30 20 20 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 should
3da40 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 free this memory
3da50 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
3da60 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
3da70 0a 2a 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 .** {H12606} Ext
3da80 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d ension loading m
3da90 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 ust be enabled u
3daa0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 sing.**
3dab0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
3dac0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
3dad0 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c )] prior to call
3dae0 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a ing this API,.**
3daf0 20 20 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 otherw
3db00 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c ise an error wil
3db10 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a l be returned..*
3db20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f /.int sqlite3_lo
3db30 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 ad_extension(.
3db40 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
3db50 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 /* Load th
3db60 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f e extension into
3db70 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 this database c
3db80 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 onnection */. c
3db90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
3dba0 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 , /* Name of
3dbb0 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 the shared libra
3dbc0 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 ry containing ex
3dbd0 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e tension */. con
3dbe0 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 st char *zProc,
3dbf0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e /* Entry poin
3dc00 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d t. Derived from
3dc10 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 zFile if 0 */.
3dc20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 char **pzErrMsg
3dc30 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 /* Put er
3dc40 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 ror message here
3dc50 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a if not 0 */.);.
3dc60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3dc70 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
3dc80 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 le Extension Loa
3dc90 64 69 6e 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 ding {H12620} <S
3dca0 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 20500>.**.** So
3dcb0 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 as not to open s
3dcc0 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e ecurity holes in
3dcd0 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 older applicati
3dce0 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 ons that are.**
3dcf0 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 unprepared to de
3dd00 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f al with extensio
3dd10 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 n loading, and a
3dd20 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 s a means of dis
3dd30 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 abling.** extens
3dd40 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c ion loading whil
3dd50 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 e evaluating use
3dd60 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 r-entered SQL, t
3dd70 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 he following API
3dd80 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 .** is provided
3dd90 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c to turn the [sql
3dda0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
3ddb0 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d ion()] mechanism
3ddc0 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a on and off..**.
3ddd0 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 ** Extension loa
3dde0 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 ding is off by d
3ddf0 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b efault. See tick
3de00 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 et #1863..**.**
3de10 7b 48 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 {H12621} Call th
3de20 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 e sqlite3_enable
3de30 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
3de40 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f ) routine with o
3de50 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 noff==1.**
3de60 20 20 20 20 74 6f 20 74 75 72 6e 20 65 78 74 65 to turn exte
3de70 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e nsion loading on
3de80 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 and call it wit
3de90 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 h onoff==0 to tu
3dea0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 rn.** i
3deb0 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e t back off again
3dec0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d ..**.** {H12622}
3ded0 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 Extension loadi
3dee0 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 ng is off by def
3def0 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ault..*/.int sql
3df00 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 ite3_enable_load
3df10 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 _extension(sqlit
3df20 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 e3 *db, int onof
3df30 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 f);../*.** CAPI3
3df40 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c REF: Automatical
3df50 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e ly Load An Exten
3df60 73 69 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c sions {H12640} <
3df70 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20500>.**.** Th
3df80 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e is API can be in
3df90 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d voked at program
3dfa0 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 startup in orde
3dfb0 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a r to register.**
3dfc0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 one or more sta
3dfd0 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 tically linked e
3dfe0 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 xtensions that w
3dff0 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 ill be available
3e000 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b .** to all new [
3e010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3e020 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ions]. {END}.**.
3e030 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
3e040 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 stores a pointer
3e050 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f to the extensio
3e060 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 n in an array th
3e070 61 74 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 at is.** obtaine
3e080 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
3e090 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 malloc()]. If y
3e0a0 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 ou run a memory
3e0b0 6c 65 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 leak checker.**
3e0c0 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 on your program
3e0d0 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 and it reports a
3e0e0 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 leak because of
3e0f0 20 74 68 69 73 20 61 72 72 61 79 2c 20 69 6e 76 this array, inv
3e100 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f oke.** [sqlite3_
3e110 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e reset_auto_exten
3e120 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f sion()] prior to
3e130 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 shutdown to fre
3e140 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a e the memory..**
3e150 0a 2a 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 69 .** {H12641} Thi
3e160 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 s function regis
3e170 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f ters an extensio
3e180 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 n entry point th
3e190 61 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 at is.**
3e1a0 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 automatically
3e1b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
3e1c0 20 61 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 a new [database
3e1d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
3e1e0 20 20 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e is open
3e1f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
3e200 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
3e210 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a te3_open16()],.*
3e220 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 * or [s
3e230 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
3e240 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 ]..**.** {H12642
3e250 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 } Duplicate exte
3e260 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 nsions are detec
3e270 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 ted so calling t
3e280 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 his routine.**
3e290 20 20 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 multiple
3e2a0 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 times with the
3e2b0 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 same extension i
3e2c0 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a s harmless..**.*
3e2d0 2a 20 7b 48 31 32 36 34 33 7d 20 54 68 69 73 20 * {H12643} This
3e2e0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 routine stores a
3e2f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
3e300 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 extension in an
3e310 61 72 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 array.**
3e320 20 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e that is obtain
3e330 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
3e340 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a _malloc()]..**.*
3e350 2a 20 7b 48 31 32 36 34 34 7d 20 41 75 74 6f 6d * {H12644} Autom
3e360 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 atic extensions
3e370 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c apply across all
3e380 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 threads..*/.int
3e390 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 sqlite3_auto_ex
3e3a0 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 tension(void *xE
3e3b0 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 2f 2a 0a ntryPoint);../*.
3e3c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
3e3d0 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 et Automatic Ext
3e3e0 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b ension Loading {
3e3f0 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30 3e H12660} <S20500>
3e400 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
3e410 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c tion disables al
3e420 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 l previously reg
3e430 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 istered automati
3e440 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e c.** extensions.
3e450 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f 65 {END} It undoe
3e460 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 s the effect of
3e470 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 all prior.** [sq
3e480 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e lite3_auto_exten
3e490 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a 2a sion()] calls..*
3e4a0 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 68 *.** {H12661} Th
3e4b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 is function disa
3e4c0 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 bles all previou
3e4d0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a sly registered.*
3e4e0 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d * autom
3e4f0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e atic extensions.
3e500 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d 20 .**.** {H12662}
3e510 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 This function di
3e520 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 sables automatic
3e530 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 extensions in a
3e540 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 ll threads..*/.v
3e550 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 oid sqlite3_rese
3e560 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e t_auto_extension
3e570 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a (void);../*.****
3e580 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 ** EXPERIMENTAL
3e590 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 - subject to cha
3e5a0 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 nge without noti
3e5b0 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ce *************
3e5c0 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 *.**.** The inte
3e5d0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 rface to the vir
3e5e0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
3e5f0 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c nism is currentl
3e600 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 y considered.**
3e610 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 to be experiment
3e620 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 al. The interfa
3e630 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 ce might change
3e640 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 in incompatible
3e650 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ways..** If this
3e660 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f is a problem fo
3e670 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 r you, do not us
3e680 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 e the interface
3e690 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a at this time..**
3e6a0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 .** When the vir
3e6b0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
3e6c0 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c nism stabilizes,
3e6d0 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 we will declare
3e6e0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 the.** interfac
3e6f0 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 e fixed, support
3e700 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 it indefinitely
3e710 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 , and remove thi
3e720 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f s comment..*/../
3e730 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 *.** Structures
3e740 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 used by the virt
3e750 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 ual table interf
3e760 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ace.*/.typedef s
3e770 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
3e780 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b ab sqlite3_vtab;
3e790 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
3e7a0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
3e7b0 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 fo sqlite3_index
3e7c0 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 _info;.typedef s
3e7d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
3e7e0 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 ab_cursor sqlite
3e7f0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 3_vtab_cursor;.t
3e800 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
3e810 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c lite3_module sql
3e820 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a ite3_module;../*
3e830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
3e840 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 rtual Table Obje
3e850 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 30 ct {H18000} <S20
3e860 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 400>.** KEYWORDS
3e870 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 : sqlite3_module
3e880 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
3e890 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 .**.** A module
3e8a0 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 is a class of vi
3e8b0 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 rtual tables. E
3e8c0 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 ach module is de
3e8d0 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 fined.** by an i
3e8e0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 nstance of the f
3e8f0 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 ollowing structu
3e900 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 re. This struct
3e910 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 ure consists.**
3e920 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 mostly of method
3e930 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 s for the module
3e940 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
3e950 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 erface is experi
3e960 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 mental and is su
3e970 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
3e980 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e or.** removal in
3e990 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
3e9a0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 of SQLite..*/.s
3e9b0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f truct sqlite3_mo
3e9c0 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 dule {. int iVe
3e9d0 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 rsion;. int (*x
3e9e0 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a Create)(sqlite3*
3e9f0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 , void *pAux,.
3ea00 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
3ea10 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 argc, const cha
3ea20 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 r *const*argv,.
3ea30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 sq
3ea40 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 lite3_vtab **ppV
3ea50 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 Tab, char**);.
3ea60 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 int (*xConnect)(
3ea70 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a sqlite3*, void *
3ea80 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 pAux,.
3ea90 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 int argc, c
3eaa0 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 onst char *const
3eab0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 *argv,.
3eac0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 sqlite3_vt
3ead0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 ab **ppVTab, cha
3eae0 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 r**);. int (*xB
3eaf0 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 estIndex)(sqlite
3eb00 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 3_vtab *pVTab, s
3eb10 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
3eb20 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 o*);. int (*xDi
3eb30 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 sconnect)(sqlite
3eb40 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
3eb50 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 int (*xDestroy
3eb60 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
3eb70 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
3eb80 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
3eb90 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 tab *pVTab, sqli
3eba0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
3ebb0 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 **ppCursor);. i
3ebc0 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
3ebd0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
3ebe0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c *);. int (*xFil
3ebf0 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ter)(sqlite3_vta
3ec00 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 b_cursor*, int i
3ec10 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 dxNum, const cha
3ec20 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 r *idxStr,.
3ec30 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
3ec40 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c rgc, sqlite3_val
3ec50 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e ue **argv);. in
3ec60 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 t (*xNext)(sqlit
3ec70 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 e3_vtab_cursor*)
3ec80 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 ;. int (*xEof)(
3ec90 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
3eca0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
3ecb0 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f Column)(sqlite3_
3ecc0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 vtab_cursor*, sq
3ecd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
3ece0 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 int);. int (*xR
3ecf0 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 owid)(sqlite3_vt
3ed00 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 ab_cursor*, sqli
3ed10 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 te3_int64 *pRowi
3ed20 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 d);. int (*xUpd
3ed30 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ate)(sqlite3_vta
3ed40 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 b *, int, sqlite
3ed50 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 3_value **, sqli
3ed60 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 te3_int64 *);.
3ed70 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 int (*xBegin)(sq
3ed80 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
3ed90 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e b);. int (*xSyn
3eda0 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 c)(sqlite3_vtab
3edb0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
3edc0 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 *xCommit)(sqlite
3edd0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
3ede0 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 int (*xRollbac
3edf0 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 k)(sqlite3_vtab
3ee00 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
3ee10 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 *xFindFunction)(
3ee20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
3ee30 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 tab, int nArg, c
3ee40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
3ee50 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
3ee60 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a void (*
3ee70 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 *pxFunc)(sqlite3
3ee80 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
3ee90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
3eea0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3eeb0 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 void **pp
3eec0 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 Arg);. int (*xR
3eed0 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 ename)(sqlite3_v
3eee0 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 tab *pVtab, cons
3eef0 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d t char *zNew);.}
3ef00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3ef10 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 F: Virtual Table
3ef20 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d Indexing Inform
3ef30 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20 3c ation {H18100} <
3ef40 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20400>.** KEYWO
3ef50 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 RDS: sqlite3_ind
3ef60 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 ex_info.** EXPER
3ef70 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
3ef80 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f e sqlite3_index_
3ef90 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 info structure a
3efa0 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 nd its substruct
3efb0 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a ures is used to.
3efc0 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 ** pass informat
3efd0 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 ion into and rec
3efe0 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 eive the reply f
3eff0 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 rom the xBestInd
3f000 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 ex.** method of
3f010 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c an sqlite3_modul
3f020 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 e. The fields u
3f030 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 nder **Inputs**
3f040 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 are the.** input
3f050 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 s to xBestIndex
3f060 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c and are read-onl
3f070 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 y. xBestIndex i
3f080 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 nserts its.** re
3f090 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a sults into the *
3f0a0 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 *Outputs** field
3f0b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f s..**.** The aCo
3f0c0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 nstraint[] array
3f0d0 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 records WHERE c
3f0e0 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 lause constraint
3f0f0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a s of the form:.*
3f100 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e *.** <pre>column
3f110 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a OP expr</pre>.*
3f120 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 *.** where OP is
3f130 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c =, <, <=,
3f140 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e >, or >=.
3f150 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 The particular
3f160 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 operator is.**
3f170 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 stored in aConst
3f180 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 raint[].op. The
3f190 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f index of the co
3f1a0 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 lumn is stored i
3f1b0 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 n.** aConstraint
3f1c0 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f [].iColumn. aCo
3f1d0 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c nstraint[].usabl
3f1e0 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 e is TRUE if the
3f1f0 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 .** expr on the
3f200 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 right-hand side
3f210 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 can be evaluated
3f220 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 (and thus the c
3f230 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 onstraint.** is
3f240 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 usable) and fals
3f250 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a e if it cannot..
3f260 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 **.** The optimi
3f270 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c zer automaticall
3f280 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 y inverts terms
3f290 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 of the form "exp
3f2a0 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 r OP column".**
3f2b0 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 and makes other
3f2c0 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 simplifications
3f2d0 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 to the WHERE cla
3f2e0 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 use in an attemp
3f2f0 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d t to.** get as m
3f300 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 any WHERE clause
3f310 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 terms into the
3f320 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 form shown above
3f330 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a as possible..**
3f340 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 The aConstraint
3f350 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 [] array only re
3f360 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 ports WHERE clau
3f370 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 se terms in the
3f380 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 correct.** form
3f390 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 that refer to th
3f3a0 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 e particular vir
3f3b0 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 tual table being
3f3c0 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 queried..**.**
3f3d0 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 Information abou
3f3e0 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 t the ORDER BY c
3f3f0 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 lause is stored
3f400 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a in aOrderBy[]..*
3f410 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 * Each term of a
3f420 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 OrderBy records
3f430 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 a column of the
3f440 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e ORDER BY clause.
3f450 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 .**.** The xBest
3f460 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 Index method mus
3f470 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 t fill aConstrai
3f480 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 ntUsage[] with i
3f490 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 nformation.** ab
3f4a0 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 out what paramet
3f4b0 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 ers to pass to x
3f4c0 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 Filter. If argv
3f4d0 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 Index>0 then.**
3f4e0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 the right-hand s
3f4f0 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 ide of the corre
3f500 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 sponding aConstr
3f510 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 aint[] is evalua
3f520 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d ted.** and becom
3f530 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 es the argvIndex
3f540 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 -th entry in arg
3f550 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 v. If aConstrai
3f560 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a ntUsage[].omit.*
3f570 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 * is true, then
3f580 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 the constraint i
3f590 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 s assumed to be
3f5a0 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 fully handled by
3f5b0 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 the.** virtual
3f5c0 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 table and is not
3f5d0 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 checked again b
3f5e0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 y SQLite..**.**
3f5f0 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 The idxNum and i
3f600 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 dxPtr values are
3f610 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 recorded and pa
3f620 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 ssed into xFilte
3f630 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 r..** sqlite3_fr
3f640 65 65 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 ee() is used to
3f650 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 6e free idxPtr if n
3f660 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 eedToFreeIdxPtr
3f670 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 is true..**.** T
3f680 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d he orderByConsum
3f690 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 ed means that ou
3f6a0 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 tput from xFilte
3f6b0 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a r will occur in.
3f6c0 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f ** the correct o
3f6d0 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 rder to satisfy
3f6e0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
3f6f0 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 use so that no s
3f700 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 eparate.** sorti
3f710 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 ng step is requi
3f720 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 red..**.** The e
3f730 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c stimatedCost val
3f740 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 ue is an estimat
3f750 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 e of the cost of
3f760 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 doing the.** pa
3f770 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e rticular lookup.
3f780 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 A full scan of
3f790 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 a table with N
3f7a0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 entries should h
3f7b0 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 ave.** a cost of
3f7c0 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 N. A binary se
3f7d0 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 arch of a table
3f7e0 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f of N entries sho
3f7f0 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f uld have a.** co
3f800 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 st of approximat
3f810 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2a 0a 2a ely log(N)..**.*
3f820 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
3f830 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
3f840 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
3f850 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
3f860 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
3f870 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
3f880 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 Lite..*/.struct
3f890 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
3f8a0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 fo {. /* Inputs
3f8b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 */. int nConst
3f8c0 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 raint;
3f8d0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e /* Number of en
3f8e0 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 tries in aConstr
3f8f0 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 aint */. struct
3f900 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
3f910 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 onstraint {.
3f920 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
3f930 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
3f940 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e lumn on left-han
3f950 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 d side of constr
3f960 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 aint */. uns
3f970 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 igned char op;
3f980 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 /* Constr
3f990 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f aint operator */
3f9a0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
3f9b0 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 har usable;
3f9c0 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 /* True if this
3f9d0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 constraint is us
3f9e0 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 able */. int
3f9f0 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 iTermOffset;
3fa00 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
3fa10 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 nternally - xBes
3fa20 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 tIndex should ig
3fa30 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f nore */. } *aCo
3fa40 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
3fa50 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 /* Table of
3fa60 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
3fa70 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 nstraints */. i
3fa80 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 nt nOrderBy;
3fa90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
3faa0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
3fab0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
3fac0 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 use */. struct
3fad0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 sqlite3_index_or
3fae0 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 derby {. int
3faf0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 iColumn;
3fb00 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e /* Column
3fb10 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 number */.
3fb20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 unsigned char de
3fb30 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 sc; /* Tru
3fb40 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c e for DESC. Fal
3fb50 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 se for ASC. */.
3fb60 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 } *aOrderBy;
3fb70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 /* T
3fb80 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
3fb90 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 se */. /* Outpu
3fba0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 ts */. struct s
3fbb0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
3fbc0 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a straint_usage {.
3fbd0 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 int argvInde
3fbe0 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 x; /*
3fbf0 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e if >0, constrain
3fc00 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 t is part of arg
3fc10 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a v to xFilter */.
3fc20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
3fc30 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 r omit; /*
3fc40 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 Do not code a te
3fc50 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 st for this cons
3fc60 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 traint */. } *a
3fc70 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b ConstraintUsage;
3fc80 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 . int idxNum;
3fc90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3fca0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 Number used to
3fcb0 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 identify the ind
3fcc0 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 ex */. char *id
3fcd0 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 xStr;
3fce0 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f /* String, po
3fcf0 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 ssibly obtained
3fd00 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
3fd10 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 loc */. int nee
3fd20 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 dToFreeIdxStr;
3fd30 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 /* Free idxS
3fd40 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 tr using sqlite3
3fd50 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 _free() if true
3fd60 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 */. int orderBy
3fd70 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 Consumed;
3fd80 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 /* True if outpu
3fd90 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 t is already ord
3fda0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 ered */. double
3fdb0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 estimatedCost;
3fdc0 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 /* Estimate
3fdd0 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 d cost of using
3fde0 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b this index */.};
3fdf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3fe00 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3fe10 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 _EQ 2.#define
3fe20 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
3fe30 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 NSTRAINT_GT 4
3fe40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3fe50 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3fe60 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 _LE 8.#define
3fe70 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
3fe80 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 NSTRAINT_LT 1
3fe90 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
3fea0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
3feb0 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 T_GE 32.#defi
3fec0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
3fed0 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 CONSTRAINT_MATCH
3fee0 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 64../*.** CAPI3
3fef0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
3ff00 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d Virtual Table Im
3ff10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 plementation {H1
3ff20 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8200} <S20400>.*
3ff30 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3ff40 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
3ff50 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 e is used to reg
3ff60 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64 75 ister a new modu
3ff70 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 0a 2a le name with a.*
3ff80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
3ff90 65 63 74 69 6f 6e 5d 2e 20 20 4d 6f 64 75 6c 65 ection]. Module
3ffa0 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 names must be r
3ffb0 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 egistered before
3ffc0 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 6e 65 77 .** creating new
3ffd0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
3ffe0 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f on the module, o
3fff0 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 0a 2a r before using.*
40000 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 * preexisting vi
40010 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 66 20 rtual tables of
40020 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a the module..**.*
40030 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
40040 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
40050 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
40060 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
40070 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
40080 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
40090 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
400a0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
400b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
400c0 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 module(. sqlite
400d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
400e0 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 /* SQLite c
400f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 onnection to reg
40100 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 ister module wit
40110 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 h */. const cha
40120 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 r *zName,
40130 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
40140 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e module */. con
40150 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c st sqlite3_modul
40160 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f e *, /* Metho
40170 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
40180 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20 e */. void *
40190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
401a0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 /* Client data
401b0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f for xCreate/xCo
401c0 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a nnect */.);../*.
401d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
401e0 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 ister A Virtual
401f0 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 Table Implementa
40200 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53 tion {H18210} <S
40210 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20400>.** EXPERI
40220 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 MENTAL.**.** Thi
40230 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 s routine is ide
40240 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73 ntical to the [s
40250 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
40260 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 20 61 dule()] method a
40270 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 bove,.** except
40280 74 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 that it allows a
40290 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 destructor func
402a0 74 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 tion to be speci
402b0 66 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 fied. It is.** e
402c0 76 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d ven more experim
402d0 65 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 ental than the r
402e0 65 73 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 est of the virtu
402f0 61 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a al tables API..*
40300 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d /.SQLITE_EXPERIM
40310 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
40320 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 3_create_module_
40330 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
40340 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
40350 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 /* SQLite conne
40360 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 ction to registe
40370 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f r module with */
40380 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
40390 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a Name, /*
403a0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 Name of the mod
403b0 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 ule */. const s
403c0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c qlite3_module *,
403d0 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 /* Methods f
403e0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f or the module */
403f0 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
40400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
40410 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 Client data for
40420 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 xCreate/xConnec
40430 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 t */. void(*xDe
40440 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 stroy)(void*)
40450 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 /* Module dest
40460 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 ructor function
40470 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
40480 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
40490 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 able Instance Ob
404a0 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 ject {H18010} <S
404b0 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 20400>.** KEYWOR
404c0 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 DS: sqlite3_vtab
404d0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
404e0 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 .**.** Every mod
404f0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
40500 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 on uses a subcla
40510 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ss of the follow
40520 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a ing structure.**
40530 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 to describe a p
40540 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e articular instan
40550 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 ce of the module
40560 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 . Each subclass
40570 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c will.** be tail
40580 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 ored to the spec
40590 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 ific needs of th
405a0 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 e module impleme
405b0 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 ntation..** The
405c0 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 purpose of this
405d0 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f superclass is to
405e0 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 define certain
405f0 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a fields that are.
40600 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c ** common to all
40610 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e module implemen
40620 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 tations..**.** V
40630 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 irtual tables me
40640 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e thods can set an
40650 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 error message b
40660 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a y assigning a.**
40670 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
40680 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
40690 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 printf()] to zEr
406a0 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f rMsg. The metho
406b0 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 d should.** take
406c0 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 care that any p
406d0 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 rior string is f
406e0 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 reed by a call t
406f0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
40700 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 )].** prior to a
40710 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 ssigning a new s
40720 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 tring to zErrMsg
40730 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72 . After the err
40740 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 or message.** is
40750 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f delivered up to
40760 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c the client appl
40770 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 ication, the str
40780 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ing will be auto
40790 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 matically.** fre
407a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 ed by sqlite3_fr
407b0 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 ee() and the zEr
407c0 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 rMsg field will
407d0 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 be zeroed. Note
407e0 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 .** that sqlite3
407f0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
40800 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 qlite3_free() ar
40810 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 e used on the zE
40820 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 rrMsg field.** s
40830 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 ince virtual tab
40840 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 les are commonly
40850 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 implemented in
40860 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 loadable extensi
40870 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 ons which.** do
40880 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 20 not have access
40890 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 to sqlite3MPrint
408a0 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 f() or sqlite3Fr
408b0 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ee()..**.** This
408c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 interface is ex
408d0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
408e0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
408f0 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 nge or.** remova
40900 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 l in future rele
40910 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
40920 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
40930 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 3_vtab {. const
40940 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
40950 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 *pModule; /* Th
40960 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 e module for thi
40970 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 s virtual table
40980 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 */. int nRef;
40990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
409a0 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 /* Used int
409b0 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 ernally */. cha
409c0 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 r *zErrMsg;
409d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
409e0 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 Error message fr
409f0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e om sqlite3_mprin
40a00 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 tf() */. /* Vir
40a10 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
40a20 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 mentations will
40a30 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 typically add ad
40a40 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
40a50 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
40a60 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
40a70 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 able Cursor Obje
40a80 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 ct {H18020} <S2
40a90 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
40aa0 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f S: sqlite3_vtab_
40ab0 63 75 72 73 6f 72 0a 2a 2a 20 45 58 50 45 52 49 cursor.** EXPERI
40ac0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 MENTAL.**.** Eve
40ad0 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d ry module implem
40ae0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 entation uses a
40af0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 subclass of the
40b00 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 following struct
40b10 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 ure.** to descri
40b20 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 be cursors that
40b30 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 point into the v
40b40 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 irtual table and
40b50 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 are used.** to
40b60 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 loop through the
40b70 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 virtual table.
40b80 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 Cursors are cre
40b90 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ated using the.*
40ba0 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f * xOpen method o
40bb0 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 f the module. E
40bc0 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 ach module imple
40bd0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 mentation will d
40be0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e efine.** the con
40bf0 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 tent of a cursor
40c00 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 structure to su
40c10 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 it its own needs
40c20 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 ..**.** This sup
40c30 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 erclass exists i
40c40 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e n order to defin
40c50 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 e fields of the
40c60 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 cursor that.** a
40c70 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c re common to all
40c80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
40c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
40ca0 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 erface is experi
40cb0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 mental and is su
40cc0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
40cd0 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e or.** removal in
40ce0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
40cf0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 of SQLite..*/.s
40d00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
40d10 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 ab_cursor {. sq
40d20 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
40d30 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 b; /* Virtu
40d40 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 al table of this
40d50 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 cursor */. /*
40d60 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d Virtual table im
40d70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 plementations wi
40d80 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 ll typically add
40d90 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
40da0 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 ds */.};../*.**
40db0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
40dc0 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 e The Schema Of
40dd0 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 A Virtual Table
40de0 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30 30 {H18280} <S20400
40df0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
40e00 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 L.**.** The xCre
40e10 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 ate and xConnect
40e20 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f methods of a mo
40e30 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c dule use the fol
40e40 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f lowing API.** to
40e50 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 declare the for
40e60 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 mat (the names a
40e70 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 nd datatypes of
40e80 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a the columns) of.
40e90 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 ** the virtual t
40ea0 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 ables they imple
40eb0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ment..**.** This
40ec0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 interface is ex
40ed0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
40ee0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
40ef0 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 nge or.** remova
40f00 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 l in future rele
40f10 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
40f20 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
40f30 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
40f40 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 e3_declare_vtab(
40f50 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 sqlite3*, const
40f60 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 char *zCreateTab
40f70 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 le);../*.** CAPI
40f80 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 3REF: Overload A
40f90 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 Function For A
40fa0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 Virtual Table {H
40fb0 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18300} <S20400>.
40fc0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
40fd0 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 **.** Virtual ta
40fe0 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 bles can provide
40ff0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 alternative imp
41000 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
41010 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 functions.** usi
41020 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 ng the xFindFunc
41030 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 tion method. Bu
41040 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e t global version
41050 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 s of those funct
41060 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 ions.** must exi
41070 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 st in order to b
41080 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a e overloaded..**
41090 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b .** This API mak
410a0 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c es sure a global
410b0 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 version of a fu
410c0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 nction with a pa
410d0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 rticular.** name
410e0 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 and number of p
410f0 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 arameters exists
41100 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 . If no such fu
41110 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a nction exists.**
41120 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 before this API
41130 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 is called, a ne
41140 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 w function is cr
41150 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c eated. The impl
41160 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
41170 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f the new functio
41180 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 n always causes
41190 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 an exception to
411a0 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a be thrown. So.*
411b0 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 * the new functi
411c0 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 on is not good f
411d0 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 or anything by i
411e0 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 tself. Its only
411f0 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 .** purpose is t
41200 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 o be a placehold
41210 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 er function that
41220 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 can be overload
41230 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c ed.** by virtual
41240 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 tables..**.** T
41250 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 his API should b
41260 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 e considered par
41270 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c t of the virtual
41280 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 table interface
41290 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 ,.** which is ex
412a0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 perimental and s
412b0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
412c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 ..*/.SQLITE_EXPE
412d0 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
412e0 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 ite3_overload_fu
412f0 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c nction(sqlite3*,
41300 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
41310 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 ncName, int nArg
41320 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e );../*.** The in
41330 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 terface to the v
41340 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 irtual-table mec
41350 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 hanism defined a
41360 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a bove (back up.**
41370 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 to a comment re
41380 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 markably similar
41390 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 to this one) is
413a0 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 currently consi
413b0 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 dered.** to be e
413c0 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 xperimental. Th
413d0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 e interface migh
413e0 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f t change in inco
413f0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a mpatible ways..*
41400 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 * If this is a p
41410 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 roblem for you,
41420 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 do not use the i
41430 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 nterface at this
41440 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 time..**.** Whe
41450 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 n the virtual-ta
41460 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 ble mechanism st
41470 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c abilizes, we wil
41480 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a l declare the.**
41490 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 interface fixed
414a0 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 , support it ind
414b0 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 efinitely, and r
414c0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 emove this comme
414d0 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 nt..**.****** EX
414e0 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 PERIMENTAL - sub
414f0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 ject to change w
41500 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a ithout notice **
41510 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a ************.*/.
41520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
41530 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 A Handle To An
41540 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 Open BLOB {H1780
41550 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 0} <S30230>.** K
41560 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 EYWORDS: {BLOB h
41570 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e andle} {BLOB han
41580 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 dles}.**.** An i
41590 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
415a0 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
415b0 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f s an open BLOB o
415c0 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 n which.** [sqli
415d0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
415e0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
415f0 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 I/O] can be per
41600 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 formed..** Objec
41610 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 ts of this type
41620 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b are created by [
41630 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
41640 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 n()].** and dest
41650 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
41660 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
41670 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
41680 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e _blob_read()] an
41690 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f d [sqlite3_blob_
416a0 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 write()] interfa
416b0 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ces.** can be us
416c0 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 ed to read or wr
416d0 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 ite small subsec
416e0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f tions of the BLO
416f0 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 B..** The [sqlit
41700 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d e3_blob_bytes()]
41710 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
41720 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 ns the size of t
41730 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 he BLOB in bytes
41740 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
41750 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 uct sqlite3_blob
41760 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a sqlite3_blob;..
41770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
41780 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 Open A BLOB For
41790 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 Incremental I/O
417a0 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 {H17810} <S30230
417b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 >.**.** This int
417c0 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 erfaces opens a
417d0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 [BLOB handle | h
417e0 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c andle] to the BL
417f0 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e OB located.** in
41800 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d row iRow, colum
41810 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 n zColumn, table
41820 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 zTable in datab
41830 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f ase zDb;.** in o
41840 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
41850 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 same BLOB that w
41860 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 ould be selected
41870 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e by:.**.** <pre>
41880 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a .** SELECT z
41890 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e Column FROM zDb.
418a0 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 zTable WHERE row
418b0 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f id = iRow;.** </
418c0 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a pre> {END}.**.**
418d0 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 If the flags pa
418e0 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a rameter is non-z
418f0 65 72 6f 2c 20 74 68 65 20 74 68 65 20 42 4c 4f ero, the the BLO
41900 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 B is opened for
41910 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 read.** and writ
41920 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 e access. If it
41930 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f is zero, the BLO
41940 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 B is opened for
41950 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a read access..**.
41960 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
41970 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 database name i
41980 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 s not the filena
41990 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 me that contains
419a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
419b0 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20 but rather the
419c0 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 symbolic name of
419d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 the database th
419e0 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 at.** is assigne
419f0 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 d when the datab
41a00 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 ase is connected
41a10 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e using [ATTACH].
41a20 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e .** For the main
41a30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
41a40 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
41a50 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 e is "main"..**
41a60 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c For TEMP tables,
41a70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
41a80 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a me is "temp"..**
41a90 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
41aa0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
41ab0 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 eturned and the
41ac0 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 new [BLOB handle
41ad0 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 ] is written.**
41ae0 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 to *ppBlob. Othe
41af0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
41b00 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
41b10 64 20 61 6e 64 20 61 6e 79 20 76 61 6c 75 65 20 d and any value
41b20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 written.** to *p
41b30 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74 pBlob should not
41b40 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 20 be used by the
41b50 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20 caller..** This
41b60 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 function sets th
41b70 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
41b80 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f ection] error co
41b90 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a de and message.*
41ba0 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 * accessible via
41bb0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
41bc0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
41bd0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 3_errmsg()]..**.
41be0 2a 2a 20 49 66 20 74 68 65 20 72 6f 77 20 74 68 ** If the row th
41bf0 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 at a BLOB handle
41c00 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f points to is mo
41c10 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 dified by an.**
41c20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 [UPDATE], [DELET
41c30 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f E], or by [ON CO
41c40 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 NFLICT] side-eff
41c50 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ects.** then the
41c60 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 BLOB handle is
41c70 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 marked as "expir
41c80 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ed"..** This is
41c90 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 true if any colu
41ca0 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 mn of the row is
41cb0 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 changed, even a
41cc0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 column.** other
41cd0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 than the one th
41ce0 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 e BLOB handle is
41cf0 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61 6c open on..** Cal
41d00 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
41d10 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 lob_read()] and
41d20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 [sqlite3_blob_wr
41d30 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 ite()] for.** a
41d40 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e expired BLOB han
41d50 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e dle fail with an
41d60 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 return code of
41d70 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a [SQLITE_ABORT]..
41d80 2a 2a 20 43 68 61 6e 67 65 73 20 77 72 69 74 74 ** Changes writt
41d90 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 en into a BLOB p
41da0 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 rior to the BLOB
41db0 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f expiring are no
41dc0 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79 t.** rollback by
41dd0 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 the expiration
41de0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 of the BLOB. Su
41df0 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 ch changes will
41e00 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f eventually.** co
41e10 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e mmit if the tran
41e20 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 saction continue
41e30 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e s to completion.
41e40 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
41e50 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 31 33 S:.**.** {H17813
41e60 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 } A successful i
41e70 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 nvocation of the
41e80 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
41e90 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c pen(D,B,T,C,R,F,
41ea0 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 P)].**
41eb0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 interface shall
41ec0 6f 70 65 6e 20 61 6e 20 5b 73 71 6c 69 74 65 33 open an [sqlite3
41ed0 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 _blob] object P
41ee0 6f 6e 20 74 68 65 20 42 4c 4f 42 0a 2a 2a 20 20 on the BLOB.**
41ef0 20 20 20 20 20 20 20 20 69 6e 20 63 6f 6c 75 6d in colum
41f00 6e 20 43 20 6f 66 20 74 68 65 20 74 61 62 6c 65 n C of the table
41f10 20 54 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 T in the databa
41f20 73 65 20 42 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 se B on.**
41f30 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 the [databas
41f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e e connection] D.
41f50 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 31 34 7d 20 .**.** {H17814}
41f60 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 A successful inv
41f70 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ocation of [sqli
41f80 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c te3_blob_open(D,
41f90 2e 2e 2e 29 5d 20 73 68 61 6c 6c 20 73 74 61 72 ...)] shall star
41fa0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 t.** a
41fb0 6e 65 77 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 new transaction
41fc0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
41fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 connection] D i
41fe0 66 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 f that.**
41ff0 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 connection is
42000 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e 20 not already in
42010 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 2a a transaction..*
42020 2a 0a 2a 2a 20 7b 48 31 37 38 31 36 7d 20 54 68 *.** {H17816} Th
42030 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
42040 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 open(D,B,T,C,R,F
42050 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 ,P)] interface s
42060 68 61 6c 6c 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 hall open.**
42070 20 20 20 20 20 20 74 68 65 20 42 4c 4f 42 20 66 the BLOB f
42080 6f 72 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 or read and writ
42090 65 20 61 63 63 65 73 73 20 69 66 20 61 6e 64 20 e access if and
420a0 6f 6e 6c 79 20 69 66 20 74 68 65 20 46 0a 2a 2a only if the F.**
420b0 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 parame
420c0 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e ter is non-zero.
420d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 31 39 7d 20 .**.** {H17819}
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 29 5d 20 69 6e 74 65 72 66 b_open()] interf
42100 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ace shall return
42110 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 0a [SQLITE_OK] on.
42120 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63 ** succ
42130 65 73 73 20 61 6e 64 20 61 6e 20 61 70 70 72 6f ess and an appro
42140 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
42150 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a de] on failure..
42160 2a 2a 0a 2a 2a 20 7b 48 31 37 38 32 31 7d 20 49 **.** {H17821} I
42170 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
42180 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 s during evaluat
42190 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
421a0 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 blob_open(D,...)
421b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ].** th
421c0 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 en subsequent ca
421d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
421e0 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 errcode(D)],.**
421f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
42200 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
42210 64 65 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 20 20 de()], .**
42220 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 [sqlite3_err
42230 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 msg(D)], and [sq
42240 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 lite3_errmsg16(D
42250 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a )] shall return.
42260 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f ** info
42270 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 72 69 rmation appropri
42280 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 72 72 ate for that err
42290 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 32 or..**.** {H1782
422a0 34 7d 20 49 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 4} If any column
422b0 20 69 6e 20 74 68 65 20 72 6f 77 20 74 68 61 74 in the row that
422c0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 a [sqlite3_blob
422d0 5d 20 68 61 73 20 6f 70 65 6e 20 69 73 0a 2a 2a ] has open is.**
422e0 20 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 change
422f0 64 20 62 79 20 61 20 73 65 70 61 72 61 74 65 20 d by a separate
42300 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c [UPDATE] or [DEL
42310 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 6f ETE] statement o
42320 72 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 r by.**
42330 20 61 6e 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 an [ON CONFLICT
42340 5d 20 73 69 64 65 20 65 66 66 65 63 74 2c 20 74 ] side effect, t
42350 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hen the [sqlite3
42360 5f 62 6c 6f 62 5d 20 73 68 61 6c 6c 0a 2a 2a 20 _blob] shall.**
42370 20 20 20 20 20 20 20 20 20 62 65 20 6d 61 72 6b be mark
42380 65 64 20 61 73 20 69 6e 76 61 6c 69 64 2e 0a 2a ed as invalid..*
42390 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
423a0 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 ob_open(. sqlit
423b0 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 e3*,. const cha
423c0 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 r *zDb,. const
423d0 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 char *zTable,.
423e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c const char *zCol
423f0 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 umn,. sqlite3_i
42400 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 nt64 iRow,. int
42410 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 flags,. sqlite
42420 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 3_blob **ppBlob.
42430 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
42440 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 EF: Close A BLOB
42450 20 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d Handle {H17830}
42460 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 <S30230>.**.**
42470 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b Closes an open [
42480 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a BLOB handle]..**
42490 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c .** Closing a BL
424a0 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 OB shall cause t
424b0 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 he current trans
424c0 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 action to commit
424d0 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 .** if there are
424e0 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c no other BLOBs,
424f0 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 no pending prep
42500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c ared statements,
42510 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 and the.** data
42520 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
42530 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 is in [autocommi
42540 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 t mode]..** If a
42550 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d ny writes were m
42560 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c ade to the BLOB,
42570 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 they might be h
42580 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 eld in cache.**
42590 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 until the close
425a0 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 operation if the
425b0 79 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 y will fit. {END
425c0 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 }.**.** Closing
425d0 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 the BLOB often f
425e0 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 orces the change
425f0 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b s.** out to disk
42600 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 and so if any I
42610 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c /O errors occur,
42620 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c they will likel
42630 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 y occur.** at th
42640 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 e time when the
42650 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 BLOB is closed.
42660 20 7b 48 31 37 38 33 33 7d 20 41 6e 79 20 65 72 {H17833} Any er
42670 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 rors that occur
42680 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e during.** closin
42690 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 g are reported a
426a0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 s a non-zero ret
426b0 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a urn value..**.**
426c0 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f The BLOB is clo
426d0 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 sed unconditiona
426e0 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 lly. Even if th
426f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
42700 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 ns.** an error c
42710 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 ode, the BLOB is
42720 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a still closed..*
42730 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
42740 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 33 33 7d 20 .**.** {H17833}
42750 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f The [sqlite3_blo
42760 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69 6e 74 65 b_close(P)] inte
42770 72 66 61 63 65 20 63 6c 6f 73 65 73 20 61 6e 20 rface closes an
42780 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 0a 2a [sqlite3_blob].*
42790 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 * objec
427a0 74 20 50 20 70 72 65 76 69 6f 75 73 6c 79 20 6f t P previously o
427b0 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c pened using [sql
427c0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
427d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 33 36 ]..**.** {H17836
427e0 7d 20 43 6c 6f 73 69 6e 67 20 61 6e 20 5b 73 71 } Closing an [sq
427f0 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 lite3_blob] obje
42800 63 74 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 ct using.**
42810 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c [sqlite3_bl
42820 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 73 68 61 6c ob_close()] shal
42830 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 l cause the curr
42840 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ent transaction
42850 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 to.** c
42860 6f 6d 6d 69 74 20 69 66 20 74 68 65 72 65 20 61 ommit if there a
42870 72 65 20 6e 6f 20 6f 74 68 65 72 20 6f 70 65 6e re no other open
42880 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 [sqlite3_blob]
42890 6f 62 6a 65 63 74 73 0a 2a 2a 20 20 20 20 20 20 objects.**
428a0 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 or [prepared
428b0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 6e 20 statements] on
428c0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
428d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
428e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 nd.** t
428f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
42900 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 ection is in [au
42910 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a tocommit mode]..
42920 2a 2a 0a 2a 2a 20 7b 48 31 37 38 33 39 7d 20 54 **.** {H17839} T
42930 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
42940 5f 63 6c 6f 73 65 28 50 29 5d 20 69 6e 74 65 72 _close(P)] inter
42950 66 61 63 65 73 20 73 68 61 6c 6c 20 63 6c 6f 73 faces shall clos
42960 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 e the.**
42970 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d [sqlite3_blob]
42980 20 6f 62 6a 65 63 74 20 50 20 75 6e 63 6f 6e 64 object P uncond
42990 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 76 65 6e 20 itionally, even
429a0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b if.** [
429b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
429c0 73 65 28 50 29 5d 20 72 65 74 75 72 6e 73 20 73 se(P)] returns s
429d0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
429e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e han [SQLITE_OK].
429f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
42a00 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 blob_close(sqlit
42a10 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a e3_blob *);../*.
42a20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 ** CAPI3REF: Ret
42a30 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 urn The Size Of
42a40 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 An Open BLOB {H1
42a50 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 7840} <S30230>.*
42a60 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 *.** Returns the
42a70 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f size in bytes o
42a80 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 f the BLOB acces
42a90 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f 70 sible via the op
42aa0 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20 68 61 6e en.** []BLOB han
42ab0 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 dle] in its only
42ac0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
42ad0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
42ae0 2a 2a 20 7b 48 31 37 38 34 33 7d 20 54 68 65 20 ** {H17843} The
42af0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 [sqlite3_blob_by
42b00 74 65 73 28 50 29 5d 20 69 6e 74 65 72 66 61 63 tes(P)] interfac
42b10 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 e returns the si
42b20 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ze.** i
42b30 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 n bytes of the B
42b40 4c 4f 42 20 74 68 61 74 20 74 68 65 20 5b 73 71 LOB that the [sq
42b50 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 lite3_blob] obje
42b60 63 74 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 ct P.**
42b70 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2f 0a 69 refers to..*/.i
42b80 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
42b90 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c bytes(sqlite3_bl
42ba0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ob *);../*.** CA
42bb0 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 PI3REF: Read Dat
42bc0 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e a From A BLOB In
42bd0 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 crementally {H17
42be0 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 850} <S30230>.**
42bf0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
42c00 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 n is used to rea
42c10 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f d data from an o
42c20 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 pen [BLOB handle
42c30 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c ] into a.** call
42c40 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 er-supplied buff
42c50 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 er. N bytes of d
42c60 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 ata are copied i
42c70 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 nto buffer Z.**
42c80 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c from the open BL
42c90 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 OB, starting at
42ca0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a offset iOffset..
42cb0 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 **.** If offset
42cc0 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 iOffset is less
42cd0 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f than N bytes fro
42ce0 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 m the end of the
42cf0 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BLOB,.** [SQLIT
42d00 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 E_ERROR] is retu
42d10 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 rned and no data
42d20 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 is read. If N
42d30 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a or iOffset is.**
42d40 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c less than zero,
42d50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
42d60 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
42d70 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e no data is read.
42d80 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 .**.** An attemp
42d90 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 t to read from a
42da0 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 n expired [BLOB
42db0 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 handle] fails wi
42dc0 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 th an.** error c
42dd0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 ode of [SQLITE_A
42de0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 BORT]..**.** On
42df0 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f success, SQLITE_
42e00 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a OK is returned..
42e10 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e ** Otherwise, an
42e20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 [error code] or
42e30 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 an [extended er
42e40 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
42e50 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 urned..**.** INV
42e60 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
42e70 48 31 37 38 35 33 7d 20 41 20 73 75 63 63 65 73 H17853} A succes
42e80 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 sful invocation
42e90 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 of [sqlite3_blob
42ea0 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 _read(P,Z,N,X)]
42eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 .** sha
42ec0 6c 6c 20 72 65 61 64 73 20 4e 20 62 79 74 65 73 ll reads N bytes
42ed0 20 6f 66 20 64 61 74 61 20 6f 75 74 20 6f 66 20 of data out of
42ee0 74 68 65 20 42 4c 4f 42 20 72 65 66 65 72 65 6e the BLOB referen
42ef0 63 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 ced by.**
42f00 20 20 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d [BLOB handle]
42f10 20 50 20 62 65 67 69 6e 6e 69 6e 67 20 61 74 20 P beginning at
42f20 6f 66 66 73 65 74 20 58 20 61 6e 64 20 73 74 6f offset X and sto
42f30 72 65 20 74 68 6f 73 65 20 62 79 74 65 73 0a 2a re those bytes.*
42f40 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 * into
42f50 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a 2a 20 buffer Z..**.**
42f60 7b 48 31 37 38 35 36 7d 20 49 6e 20 5b 73 71 6c {H17856} In [sql
42f70 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 ite3_blob_read(P
42f80 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 74 68 65 20 ,Z,N,X)] if the
42f90 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 size of the BLOB
42fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
42fb0 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 62 79 less than N+X by
42fc0 74 65 73 2c 20 74 68 65 6e 20 74 68 65 20 66 75 tes, then the fu
42fd0 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6c 65 61 nction shall lea
42fe0 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ve the.**
42ff0 20 20 20 5a 20 62 75 66 66 65 72 20 75 6e 63 68 Z buffer unch
43000 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
43010 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
43020 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 35 39 7d 20 .**.** {H17859}
43030 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 In [sqlite3_blob
43040 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 _read(P,Z,N,X)]
43050 69 66 20 58 20 6f 72 20 4e 20 69 73 20 6c 65 73 if X or N is les
43060 73 20 74 68 61 6e 20 7a 65 72 6f 0a 2a 2a 20 20 s than zero.**
43070 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 then the
43080 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 function shall
43090 6c 65 61 76 65 20 74 68 65 20 5a 20 62 75 66 66 leave the Z buff
430a0 65 72 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 er unchanged.**
430b0 20 20 20 20 20 20 20 20 20 61 6e 64 20 72 65 74 and ret
430c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
430d0 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 36 R]..**.** {H1786
430e0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
430f0 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c blob_read(P,Z,N,
43100 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 X)] interface sh
43110 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 all return [SQLI
43120 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 TE_OK].**
43130 20 20 20 69 66 20 4e 20 62 79 74 65 73 20 61 72 if N bytes ar
43140 65 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 72 e successfully r
43150 65 61 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 ead into buffer
43160 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 36 33 Z..**.** {H17863
43170 7d 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 } If the [BLOB h
43180 61 6e 64 6c 65 5d 20 50 20 69 73 20 65 78 70 69 andle] P is expi
43190 72 65 64 20 61 6e 64 20 58 20 61 6e 64 20 4e 20 red and X and N
431a0 61 72 65 20 77 69 74 68 69 6e 20 62 6f 75 6e 64 are within bound
431b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 s.** th
431c0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 en [sqlite3_blob
431d0 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 _read(P,Z,N,X)]
431e0 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 shall leave the
431f0 5a 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 20 20 Z buffer.**
43200 20 20 20 20 20 75 6e 63 68 61 6e 67 65 64 20 61 unchanged a
43210 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
43220 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ABORT]..**.**
43230 7b 48 31 37 38 36 35 7d 20 49 66 20 74 68 65 20 {H17865} If the
43240 72 65 71 75 65 73 74 65 64 20 72 65 61 64 20 63 requested read c
43250 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 6f 6d 70 ould not be comp
43260 6c 65 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 leted,.**
43270 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f the [sqlite3_
43280 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c blob_read(P,Z,N,
43290 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 X)] interface sh
432a0 61 6c 6c 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a all return an.**
432b0 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 approp
432c0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
432d0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
432e0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
432f0 2a 2a 20 7b 48 31 37 38 36 38 7d 20 49 66 20 61 ** {H17868} If a
43300 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
43310 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e uring evaluation
43320 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f of [sqlite3_blo
43330 62 5f 72 65 61 64 28 50 2c 2e 2e 2e 29 5d 0a 2a b_read(P,...)].*
43340 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
43350 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
43360 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
43370 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 code(D)],.**
43380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 [sqlite3_e
43390 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
433a0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
433b0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
433c0 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 D)], and [sqlite
433d0 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20 73 3_errmsg16(D)] s
433e0 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 hall return.**
433f0 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 informat
43400 69 6f 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 ion appropriate
43410 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2c 20 for that error,
43420 77 68 65 72 65 20 44 20 69 73 20 74 68 65 0a 2a where D is the.*
43430 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 * [data
43440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
43450 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 that was used t
43460 6f 20 6f 70 65 6e 20 74 68 65 20 5b 42 4c 4f 42 o open the [BLOB
43470 20 68 61 6e 64 6c 65 5d 20 50 2e 0a 2a 2f 0a 69 handle] P..*/.i
43480 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
43490 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f read(sqlite3_blo
434a0 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e b *, void *Z, in
434b0 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 t N, int iOffset
434c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
434d0 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 EF: Write Data I
434e0 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 nto A BLOB Incre
434f0 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 mentally {H17870
43500 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a } <S30230>.**.**
43510 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
43520 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 s used to write
43530 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 data into an ope
43540 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 n [BLOB handle]
43550 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 from a.** caller
43560 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 -supplied buffer
43570 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 . N bytes of dat
43580 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f a are copied fro
43590 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a m the buffer Z.*
435a0 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 * into the open
435b0 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 BLOB, starting a
435c0 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 t offset iOffset
435d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b ..**.** If the [
435e0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 BLOB handle] pas
435f0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
43600 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f argument was no
43610 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 t opened for.**
43620 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 writing (the fla
43630 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 gs parameter to
43640 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
43650 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c en()] was zero),
43660 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f .** this functio
43670 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 n returns [SQLIT
43680 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a E_READONLY]..**.
43690 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
436a0 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 may only modify
436b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 the contents of
436c0 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 the BLOB; it is
436d0 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 .** not possible
436e0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 to increase the
436f0 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 size of a BLOB
43700 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a using this API..
43710 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 ** If offset iOf
43720 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 fset is less tha
43730 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 n N bytes from t
43740 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c he end of the BL
43750 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 OB,.** [SQLITE_E
43760 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
43770 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
43780 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 written. If N
43790 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 is.** less than
437a0 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 zero [SQLITE_ERR
437b0 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OR] is returned
437c0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 and no data is w
437d0 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e ritten..**.** An
437e0 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 attempt to writ
437f0 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 e to an expired
43800 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 [BLOB handle] fa
43810 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 ils with an.** e
43820 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 rror code of [SQ
43830 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72 LITE_ABORT]. Wr
43840 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 ites to the BLOB
43850 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a that occurred.*
43860 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c * before the [BL
43870 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 OB handle] expir
43880 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 ed are not rolle
43890 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a d back by the.**
438a0 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 expiration of t
438b0 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 he handle, thoug
438c0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 h of course thos
438d0 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a e changes might.
438e0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 ** have been ove
438f0 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 rwritten by the
43900 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 statement that e
43910 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 xpired the BLOB
43920 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 handle.** or by
43930 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e other independen
43940 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a t statements..**
43950 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
43960 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 SQLITE_OK is ret
43970 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 urned..** Otherw
43980 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 ise, an [error
43990 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 code] or an [ext
439a0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
439b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
439c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
439d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 33 7d 20 .**.** {H17873}
439e0 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 A successful inv
439f0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ocation of [sqli
43a00 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 te3_blob_write(P
43a10 2c 5a 2c 4e 2c 58 29 5d 0a 2a 2a 20 20 20 20 20 ,Z,N,X)].**
43a20 20 20 20 20 20 73 68 61 6c 6c 20 77 72 69 74 65 shall write
43a30 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 N bytes of data
43a40 20 66 72 6f 6d 20 62 75 66 66 65 72 20 5a 20 69 from buffer Z i
43a50 6e 74 6f 20 74 68 65 20 42 4c 4f 42 20 0a 2a 2a nto the BLOB .**
43a60 20 20 20 20 20 20 20 20 20 20 72 65 66 65 72 65 refere
43a70 6e 63 65 64 20 62 79 20 5b 42 4c 4f 42 20 68 61 nced by [BLOB ha
43a80 6e 64 6c 65 5d 20 50 20 62 65 67 69 6e 6e 69 6e ndle] P beginnin
43a90 67 20 61 74 20 6f 66 66 73 65 74 20 58 20 69 6e g at offset X in
43aa0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 to.** t
43ab0 68 65 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 7b he BLOB..**.** {
43ac0 48 31 37 38 37 34 7d 20 49 6e 20 74 68 65 20 61 H17874} In the a
43ad0 62 73 65 6e 63 65 20 6f 66 20 6f 74 68 65 72 20 bsence of other
43ae0 6f 76 65 72 72 69 64 64 69 6e 67 20 63 68 61 6e overridding chan
43af0 67 65 73 2c 20 74 68 65 20 63 68 61 6e 67 65 73 ges, the changes
43b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 .** wri
43b10 74 74 65 6e 20 74 6f 20 61 20 42 4c 4f 42 20 62 tten to a BLOB b
43b20 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f y [sqlite3_blob_
43b30 77 72 69 74 65 28 29 5d 20 73 68 61 6c 6c 0a 2a write()] shall.*
43b40 2a 20 20 20 20 20 20 20 20 20 20 72 65 6d 61 69 * remai
43b50 6e 20 69 6e 20 65 66 66 65 63 74 20 61 66 74 65 n in effect afte
43b60 72 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 r the associated
43b70 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 [BLOB handle] e
43b80 78 70 69 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 xpires..**.** {H
43b90 31 37 38 37 35 7d 20 49 66 20 74 68 65 20 5b 42 17875} If the [B
43ba0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 77 61 LOB handle] P wa
43bb0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
43bc0 64 69 6e 67 20 6f 6e 6c 79 20 74 68 65 6e 0a 2a ding only then.*
43bd0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 69 6e * an in
43be0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
43bf0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
43c00 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c 20 P,Z,N,X)] shall
43c10 6c 65 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 leave.**
43c20 20 20 74 68 65 20 72 65 66 65 72 65 6e 63 65 64 the referenced
43c30 20 42 4c 4f 42 20 75 6e 63 68 61 6e 67 65 64 20 BLOB unchanged
43c40 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
43c50 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a TE_READONLY]..**
43c60 0a 2a 2a 20 7b 48 31 37 38 37 36 7d 20 49 66 20 .** {H17876} If
43c70 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
43c80 42 4c 4f 42 20 72 65 66 65 72 65 6e 63 65 64 20 BLOB referenced
43c90 62 79 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d by [BLOB handle]
43ca0 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 P is.**
43cb0 20 20 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 less than N+X
43cc0 62 79 74 65 73 20 74 68 65 6e 20 5b 73 71 6c 69 bytes then [sqli
43cd0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 te3_blob_write(P
43ce0 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c 0a 2a ,Z,N,X)] shall.*
43cf0 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 * leave
43d00 20 74 68 65 20 42 4c 4f 42 20 75 6e 63 68 61 6e the BLOB unchan
43d10 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b ged and return [
43d20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a SQLITE_ERROR]..*
43d30 2a 0a 2a 2a 20 7b 48 31 37 38 37 37 7d 20 49 66 *.** {H17877} If
43d40 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c the [BLOB handl
43d50 65 5d 20 50 20 69 73 20 65 78 70 69 72 65 64 20 e] P is expired
43d60 61 6e 64 20 58 20 61 6e 64 20 4e 20 61 72 65 20 and X and N are
43d70 77 69 74 68 69 6e 20 62 6f 75 6e 64 73 0a 2a 2a within bounds.**
43d80 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b then [
43d90 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 sqlite3_blob_rea
43da0 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c d(P,Z,N,X)] shal
43db0 6c 20 6c 65 61 76 65 20 74 68 65 20 42 4c 4f 42 l leave the BLOB
43dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 63 .** unc
43dd0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 hanged and retur
43de0 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d n [SQLITE_ABORT]
43df0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 39 7d ..**.** {H17879}
43e00 20 49 66 20 58 20 6f 72 20 4e 20 61 72 65 20 6c If X or N are l
43e10 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 74 68 ess than zero th
43e20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 en [sqlite3_blob
43e30 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d _write(P,Z,N,X)]
43e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 .** sha
43e50 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 42 4c 4f ll leave the BLO
43e60 42 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 B referenced by
43e70 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 [BLOB handle] P
43e80 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 20 20 20 unchanged.**
43e90 20 20 20 20 20 20 61 6e 64 20 72 65 74 75 72 6e and return
43ea0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
43eb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 38 32 7d 20 .**.** {H17882}
43ec0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f The [sqlite3_blo
43ed0 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 b_write(P,Z,N,X)
43ee0 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
43ef0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 l return.**
43f00 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d [SQLITE_OK]
43f10 20 69 66 20 4e 20 62 79 74 65 73 20 77 68 65 72 if N bytes wher
43f20 65 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 77 e successfully w
43f30 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
43f40 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 BLOB..**.** {H17
43f50 38 38 35 7d 20 49 66 20 74 68 65 20 72 65 71 75 885} If the requ
43f60 65 73 74 65 64 20 77 72 69 74 65 20 63 6f 75 6c ested write coul
43f70 64 20 6e 6f 74 20 62 65 20 63 6f 6d 70 6c 65 74 d not be complet
43f80 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ed,.**
43f90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f the [sqlite3_blo
43fa0 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 b_write(P,Z,N,X)
43fb0 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
43fc0 6c 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 20 l return an.**
43fd0 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69 appropri
43fe0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
43ff0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 or [extended er
44000 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a ror code]..**.**
44010 20 7b 48 31 37 38 38 38 7d 20 49 66 20 61 6e 20 {H17888} If an
44020 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
44030 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f ing evaluation o
44040 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f f [sqlite3_blob_
44050 77 72 69 74 65 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a write(D,...)].**
44060 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 73 then s
44070 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
44080 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
44090 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 ode(D)],.**
440a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 [sqlite3_ex
440b0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
440c0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
440d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 sqlite3_errmsg(D
440e0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
440f0 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20 73 68 _errmsg16(D)] sh
44100 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 all return.**
44110 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 informati
44120 6f 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 on appropriate f
44130 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a or that error..*
44140 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
44150 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 ob_write(sqlite3
44160 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 _blob *, const v
44170 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 oid *z, int n, i
44180 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a nt iOffset);../*
44190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
441a0 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 rtual File Syste
441b0 6d 20 4f 62 6a 65 63 74 73 20 7b 48 31 31 32 30 m Objects {H1120
441c0 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 0} <S20100>.**.*
441d0 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 * A virtual file
441e0 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 system (VFS) is
441f0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d an [sqlite3_vfs]
44200 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 object.** that
44210 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 SQLite uses to i
44220 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 nteract.** with
44230 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f the underlying o
44240 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
44250 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 Most SQLite bu
44260 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 ilds come with a
44270 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 .** single defau
44280 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61 lt VFS that is a
44290 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 ppropriate for t
442a0 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 he host computer
442b0 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 ..** New VFSes c
442c0 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 an be registered
442d0 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 and existing VF
442e0 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 Ses can be unreg
442f0 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 istered..** The
44300 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 following interf
44310 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 aces are provide
44320 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
44330 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 ite3_vfs_find()
44340 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
44350 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
44360 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e VFS given its n
44370 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 ame..** Names ar
44380 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 e case sensitive
44390 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a ..** Names are z
443a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
443b0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
443c0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 If there is no
443d0 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f match, a NULL po
443e0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
443f0 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d d..** If zVfsNam
44400 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 e is NULL then t
44410 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 he default VFS i
44420 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
44430 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 * New VFSes are
44440 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 registered with
44450 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
44460 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 ster()..** Each
44470 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 new VFS becomes
44480 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
44490 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 if the makeDflt
444a0 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 flag is set..**
444b0 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e The same VFS can
444c0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d be registered m
444d0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 ultiple times wi
444e0 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a thout injury..**
444f0 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 To make an exis
44500 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 ting VFS into th
44510 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 e default VFS, r
44520 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e egister it again
44530 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b .** with the mak
44540 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 eDflt flag set.
44550 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e If two differen
44560 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 t VFSes with the
44570 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 .** same name ar
44580 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 e registered, th
44590 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
445a0 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a defined. If a.*
445b0 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 * VFS is registe
445c0 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 red with a name
445d0 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 that is NULL or
445e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
445f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 .** then the beh
44600 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
44610 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 ed..**.** Unregi
44620 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20 ster a VFS with
44630 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f the sqlite3_vfs_
44640 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 unregister() int
44650 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 erface..** If th
44660 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 e default VFS is
44670 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 unregistered, a
44680 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68 nother VFS is ch
44690 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 osen as.** the d
446a0 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f efault. The cho
446b0 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 ice for the new
446c0 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79 VFS is arbitrary
446d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
446e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 30 TS:.**.** {H1120
446f0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
44700 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20 69 6e 74 vfs_find(N)] int
44710 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
44720 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
44730 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 ** regi
44740 73 74 65 72 65 64 20 5b 73 71 6c 69 74 65 33 5f stered [sqlite3_
44750 76 66 73 5d 20 6f 62 6a 65 63 74 20 77 68 6f 73 vfs] object whos
44760 65 20 6e 61 6d 65 20 65 78 61 63 74 6c 79 20 6d e name exactly m
44770 61 74 63 68 65 73 0a 2a 2a 20 20 20 20 20 20 20 atches.**
44780 20 20 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d the zero-term
44790 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
447a0 69 6e 67 20 4e 2c 20 6f 72 20 69 74 20 72 65 74 ing N, or it ret
447b0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 0a 2a 2a 20 urns NULL if.**
447c0 20 20 20 20 20 20 20 20 20 74 68 65 72 65 20 69 there i
447d0 73 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2a 0a 2a s no match..**.*
447e0 2a 20 7b 48 31 31 32 30 36 7d 20 49 66 20 74 68 * {H11206} If th
447f0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f e N parameter to
44800 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 [sqlite3_vfs_fi
44810 6e 64 28 4e 29 5d 20 69 73 20 4e 55 4c 4c 20 74 nd(N)] is NULL t
44820 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
44830 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 the function ret
44840 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
44850 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 o the default [s
44860 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 20 qlite3_vfs].**
44870 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 69 object i
44880 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 2c 20 f there is one,
44890 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 or NULL if there
448a0 20 69 73 20 6e 6f 20 64 65 66 61 75 6c 74 0a 2a is no default.*
448b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
448c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
448d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 30 39 7d 20 .**.** {H11209}
448e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
448f0 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29 5d 20 _register(P,F)]
44900 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
44910 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ers the.**
44920 20 20 20 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 well-formed
44930 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
44940 6a 65 63 74 20 50 20 75 73 69 6e 67 20 74 68 65 ject P using the
44950 20 6e 61 6d 65 20 67 69 76 65 6e 0a 2a 2a 20 20 name given.**
44960 20 20 20 20 20 20 20 20 62 79 20 74 68 65 20 7a by the z
44970 4e 61 6d 65 20 66 69 65 6c 64 20 6f 66 20 74 68 Name field of th
44980 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 e object..**.**
44990 7b 48 31 31 32 31 32 7d 20 55 73 69 6e 67 20 74 {H11212} Using t
449a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
449b0 72 65 67 69 73 74 65 72 28 50 2c 46 29 5d 20 69 register(P,F)] i
449c0 6e 74 65 72 66 61 63 65 20 74 6f 20 72 65 67 69 nterface to regi
449d0 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ster.**
449e0 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74 the same [sqlit
449f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 6d e3_vfs] object m
44a00 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 69 73 ultiple times is
44a10 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
44a20 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 31 35 p..**.** {H11215
44a30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
44a40 66 73 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29 fs_register(P,F)
44a50 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 ] interface make
44a60 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 s the [sqlite3_v
44a70 66 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 fs].**
44a80 6f 62 6a 65 63 74 20 50 20 74 68 65 20 64 65 66 object P the def
44a90 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
44aa0 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 46 20 69 s] object if F i
44ab0 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a s non-zero..**.*
44ac0 2a 20 7b 48 31 31 32 31 38 7d 20 54 68 65 20 5b * {H11218} The [
44ad0 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
44ae0 67 69 73 74 65 72 28 50 29 5d 20 69 6e 74 65 72 gister(P)] inter
44af0 66 61 63 65 20 75 6e 72 65 67 69 73 74 65 72 73 face unregisters
44b00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
44b10 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
44b20 62 6a 65 63 74 20 50 20 73 6f 20 74 68 61 74 20 bject P so that
44b30 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
44b40 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 returned by.**
44b50 20 20 20 20 20 20 20 20 73 75 62 73 65 71 75 65 subseque
44b60 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
44b70 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d ite3_vfs_find()]
44b80 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 ..*/.sqlite3_vfs
44b90 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 *sqlite3_vfs_fi
44ba0 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a nd(const char *z
44bb0 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 VfsName);.int sq
44bc0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
44bd0 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c er(sqlite3_vfs*,
44be0 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a int makeDflt);.
44bf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f int sqlite3_vfs_
44c00 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 unregister(sqlit
44c10 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a e3_vfs*);../*.**
44c20 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
44c30 65 73 20 7b 48 31 37 30 30 30 7d 20 3c 53 32 30 es {H17000} <S20
44c40 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 000>.**.** The S
44c50 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 QLite core uses
44c60 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 these routines f
44c70 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e or thread.** syn
44c80 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 chronization. Th
44c90 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e ough they are in
44ca0 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 tended for inter
44cb0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 nal.** use by SQ
44cc0 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 Lite, code that
44cd0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 links against SQ
44ce0 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 Lite is.** permi
44cf0 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 tted to use any
44d00 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
44d10 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c s..**.** The SQL
44d20 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 ite source code
44d30 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c contains multipl
44d40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
44d50 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 s.** of these mu
44d60 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 tex routines. A
44d70 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d n appropriate im
44d80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
44d90 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f is selected auto
44da0 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d matically at com
44db0 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 pile-time. The
44dc0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 following.** imp
44dd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 lementations are
44de0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
44df0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a e SQLite core:.*
44e00 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
44e10 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
44e20 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 _OS2.** <li> S
44e30 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 QLITE_MUTEX_PTHR
44e40 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 EAD.** <li> SQ
44e50 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a LITE_MUTEX_W32.*
44e60 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f * <li> SQLITE_
44e70 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f MUTEX_NOOP.** </
44e80 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ul>.**.** The SQ
44e90 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 LITE_MUTEX_NOOP
44ea0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
44eb0 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 s a set of routi
44ec0 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 nes.** that does
44ed0 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 no real locking
44ee0 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 and is appropri
44ef0 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a ate for use in.*
44f00 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 * a single-threa
44f10 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e ded application.
44f20 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 The SQLITE_MUT
44f30 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 EX_OS2,.** SQLIT
44f40 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c E_MUTEX_PTHREAD,
44f50 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 and SQLITE_MUTE
44f60 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 X_W32 implementa
44f70 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 tions.** are app
44f80 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 ropriate for use
44f90 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 on OS/2, Unix,
44fa0 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a and Windows..**.
44fb0 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 ** If SQLite is
44fc0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
44fd0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 e SQLITE_MUTEX_A
44fe0 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 73 PPDEF preprocess
44ff0 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 or.** macro defi
45000 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c ned (with "-DSQL
45010 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 ITE_MUTEX_APPDEF
45020 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 =1"), then no mu
45030 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 tex.** implement
45040 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 ation is include
45050 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 d with the libra
45060 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 ry. In this case
45070 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 the.** applicat
45080 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
45090 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 a custom mutex i
450a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 mplementation us
450b0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ing the.** [SQLI
450c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d TE_CONFIG_MUTEX]
450d0 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 option of the s
450e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
450f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f function.** befo
45100 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 re calling sqlit
45110 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
45120 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62 or any other pub
45130 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 lic sqlite3_.**
45140 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 function that ca
45150 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 lls sqlite3_init
45160 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 ialize()..**.**
45170 7b 48 31 37 30 31 31 7d 20 54 68 65 20 73 71 6c {H17011} The sql
45180 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
45190 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 () routine alloc
451a0 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 ates a new.** mu
451b0 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 tex and returns
451c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e a pointer to it.
451d0 20 7b 48 31 37 30 31 32 7d 20 49 66 20 69 74 20 {H17012} If it
451e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 returns NULL.**
451f0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 that means that
45200 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f a mutex could no
45210 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 t be allocated.
45220 7b 48 31 37 30 31 33 7d 20 53 51 4c 69 74 65 0a {H17013} SQLite.
45230 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 ** will unwind i
45240 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 ts stack and ret
45250 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 48 urn an error. {H
45260 31 37 30 31 34 7d 20 54 68 65 20 61 72 67 75 6d 17014} The argum
45270 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
45280 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 3_mutex_alloc()
45290 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 is one of these
452a0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
452b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
452c0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
452d0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e TEX_FAST.** <li>
452e0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 SQLITE_MUTEX_R
452f0 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e ECURSIVE.** <li>
45300 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
45310 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 TATIC_MASTER.**
45320 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
45330 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a EX_STATIC_MEM.**
45340 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
45350 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a TEX_STATIC_MEM2.
45360 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
45370 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e MUTEX_STATIC_PRN
45380 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 G.** <li> SQLIT
45390 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
453a0 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 RU.** <li> SQLI
453b0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
453c0 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a LRU2.** </ul>.**
453d0 0a 2a 2a 20 7b 48 31 37 30 31 35 7d 20 54 68 65 .** {H17015} The
453e0 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 first two const
453f0 61 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69 74 ants cause sqlit
45400 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
45410 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 to create.** a
45420 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65 20 new mutex. The
45430 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 new mutex is rec
45440 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 ursive when SQLI
45450 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
45460 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 VE.** is used bu
45470 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c t not necessaril
45480 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 y so when SQLITE
45490 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 _MUTEX_FAST is u
454a0 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 sed. {END}.** Th
454b0 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e e mutex implemen
454c0 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 tation does not
454d0 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 need to make a d
454e0 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 istinction.** be
454f0 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 tween SQLITE_MUT
45500 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 EX_RECURSIVE and
45510 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
45520 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a ST if it does.**
45530 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 7b not want to. {
45540 48 31 37 30 31 36 7d 20 42 75 74 20 53 51 4c 69 H17016} But SQLi
45550 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 te will only req
45560 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76 65 uest a recursive
45570 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 mutex in.** cas
45580 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61 6c es where it real
45590 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 7b ly needs one. {
455a0 45 4e 44 7d 20 49 66 20 61 20 66 61 73 74 65 72 END} If a faster
455b0 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d non-recursive m
455c0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
455d0 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 tation is availa
455e0 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 ble on the host
455f0 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 platform, the mu
45600 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a tex subsystem.**
45610 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 might return su
45620 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 ch a mutex in re
45630 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 sponse to SQLITE
45640 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a _MUTEX_FAST..**.
45650 2a 2a 20 7b 48 31 37 30 31 37 7d 20 54 68 65 20 ** {H17017} The
45660 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 other allowed pa
45670 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 rameters to sqli
45680 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
45690 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a ) each return.**
456a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
456b0 73 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 static preexisti
456c0 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 20 ng mutex. {END}
456d0 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 Four static mut
456e0 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 exes are.** used
456f0 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 by the current
45700 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 version of SQLit
45710 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 e. Future versi
45720 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ons of SQLite.**
45730 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f may add additio
45740 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 nal static mutex
45750 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 es. Static mute
45760 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 xes are for inte
45770 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 rnal.** use by S
45780 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 QLite only. App
45790 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
457a0 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 se SQLite mutexe
457b0 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 s should.** use
457c0 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 only the dynamic
457d0 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 mutexes returne
457e0 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 d by SQLITE_MUTE
457f0 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c X_FAST or.** SQL
45800 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
45810 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 IVE..**.** {H170
45820 31 38 7d 20 4e 6f 74 65 20 74 68 61 74 20 69 66 18} Note that if
45830 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 one of the dyna
45840 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 mic mutex parame
45850 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 ters (SQLITE_MUT
45860 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 EX_FAST.** or SQ
45870 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
45880 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68 SIVE) is used th
45890 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 en sqlite3_mutex
458a0 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 _alloc().** retu
458b0 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 rns a different
458c0 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 mutex on every c
458d0 61 6c 6c 2e 20 20 7b 48 31 37 30 33 34 7d 20 42 all. {H17034} B
458e0 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 ut for the stati
458f0 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 c.** mutex types
45900 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 , the same mutex
45910 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 is returned on
45920 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 every call that
45930 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 has.** the same
45940 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a type number..**.
45950 2a 2a 20 7b 48 31 37 30 31 39 7d 20 54 68 65 20 ** {H17019} The
45960 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
45970 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 ee() routine dea
45980 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 llocates a previ
45990 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ously.** allocat
459a0 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ed dynamic mutex
459b0 2e 20 7b 48 31 37 30 32 30 7d 20 53 51 4c 69 74 . {H17020} SQLit
459c0 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 e is careful to
459d0 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 deallocate every
459e0 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 .** dynamic mute
459f0 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 x that it alloca
45a00 74 65 73 2e 20 7b 41 31 37 30 32 31 7d 20 54 68 tes. {A17021} Th
45a10 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 e dynamic mutexe
45a20 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e s must not be in
45a30 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65 .** use when the
45a40 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 y are deallocate
45a50 64 2e 20 7b 41 31 37 30 32 32 7d 20 41 74 74 65 d. {A17022} Atte
45a60 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f mpting to deallo
45a70 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a cate a static.**
45a80 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 mutex results i
45a90 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
45aa0 76 69 6f 72 2e 20 7b 48 31 37 30 32 33 7d 20 53 vior. {H17023} S
45ab0 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c QLite never deal
45ac0 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 locates.** a sta
45ad0 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d tic mutex. {END}
45ae0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
45af0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 e3_mutex_enter()
45b00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
45b10 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 ex_try() routine
45b20 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 s attempt.** to
45b30 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 7b enter a mutex. {
45b40 48 31 37 30 32 34 7d 20 49 66 20 61 6e 6f 74 68 H17024} If anoth
45b50 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 er thread is alr
45b60 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 eady within the
45b70 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 mutex,.** sqlite
45b80 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 3_mutex_enter()
45b90 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 will block and s
45ba0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
45bb0 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a () will return.*
45bc0 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 7b * SQLITE_BUSY. {
45bd0 48 31 37 30 32 35 7d 20 20 54 68 65 20 73 71 6c H17025} The sql
45be0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
45bf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
45c00 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a ns [SQLITE_OK].*
45c10 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 * upon successfu
45c20 6c 20 65 6e 74 72 79 2e 20 20 7b 48 31 37 30 32 l entry. {H1702
45c30 36 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 6} Mutexes creat
45c40 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 ed using.** SQLI
45c50 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
45c60 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 VE can be entere
45c70 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 d multiple times
45c80 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 by the same thr
45c90 65 61 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 37 7d ead..** {H17027}
45ca0 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 In such cases t
45cb0 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 he,.** mutex mus
45cc0 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 t be exited an e
45cd0 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 qual number of t
45ce0 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 imes before anot
45cf0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 her thread.** ca
45d00 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31 37 30 32 n enter. {A1702
45d10 38 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 74 8} If the same t
45d20 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 hread tries to e
45d30 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a nter any other.*
45d40 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 * kind of mutex
45d50 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 more than once,
45d60 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
45d70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48 undefined..** {H
45d80 31 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69 17029} SQLite wi
45d90 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 ll never exhibit
45da0 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f .** such behavio
45db0 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 r in its own use
45dc0 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a of mutexes..**.
45dd0 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 ** Some systems
45de0 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 (for example, Wi
45df0 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 ndows 95) do not
45e00 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 support the ope
45e10 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d ration.** implem
45e20 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 ented by sqlite3
45e30 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f _mutex_try(). O
45e40 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c n those systems,
45e50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
45e60 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 ry().** will alw
45e70 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 ays return SQLIT
45e80 45 5f 42 55 53 59 2e 20 20 7b 48 31 37 30 33 30 E_BUSY. {H17030
45e90 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 } The SQLite cor
45ea0 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 e only ever uses
45eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 .** sqlite3_mute
45ec0 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 x_try() as an op
45ed0 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 timization so th
45ee0 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 is is acceptable
45ef0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
45f00 20 7b 48 31 37 30 33 31 7d 20 54 68 65 20 73 71 {H17031} The sq
45f10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
45f20 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 e() routine exit
45f30 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 s a mutex that w
45f40 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 as.** previously
45f50 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 entered by the
45f60 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 7b 41 same thread. {A
45f70 31 37 30 33 32 7d 20 54 68 65 20 62 65 68 61 76 17032} The behav
45f80 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 ior.** is undefi
45f90 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 ned if the mutex
45fa0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
45fb0 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 y entered by the
45fc0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 .** calling thre
45fd0 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 ad or is not cur
45fe0 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 rently allocated
45ff0 2e 20 20 7b 48 31 37 30 33 33 7d 20 53 51 4c 69 . {H17033} SQLi
46000 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 te will.** never
46010 20 64 6f 20 65 69 74 68 65 72 2e 20 7b 45 4e 44 do either. {END
46020 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 }.**.** If the a
46030 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
46040 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 e3_mutex_enter()
46050 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f , sqlite3_mutex_
46060 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c try(), or.** sql
46070 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
46080 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
46090 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 nter, then all t
460a0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hree routines.**
460b0 20 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 behave as no-op
460c0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 s..**.** See als
460d0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 o: [sqlite3_mute
460e0 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 x_held()] and [s
460f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
46100 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 held()]..*/.sqli
46110 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 te3_mutex *sqlit
46120 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 e3_mutex_alloc(i
46130 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
46140 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 3_mutex_free(sql
46150 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f ite3_mutex*);.vo
46160 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 id sqlite3_mutex
46170 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d _enter(sqlite3_m
46180 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 utex*);.int sqli
46190 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 te3_mutex_try(sq
461a0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 lite3_mutex*);.v
461b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 oid sqlite3_mute
461c0 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f x_leave(sqlite3_
461d0 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 mutex*);../*.**
461e0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
461f0 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b Methods Object {
46200 48 31 37 31 32 30 7d 20 3c 53 32 30 31 33 30 3e H17120} <S20130>
46210 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
46220 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
46230 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 ce of this struc
46240 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 68 65 ture defines the
46250 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 low-level routi
46260 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 nes.** used to a
46270 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65 20 llocate and use
46280 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 mutexes..**.** U
46290 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 sually, the defa
462a0 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d ult mutex implem
462b0 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 entations provid
462c0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 72 65 ed by SQLite are
462d0 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c 20 .** sufficient,
462e0 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 65 72 however the user
462f0 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 has the option
46300 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e 67 20 of substituting
46310 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c a custom.** impl
46320 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 ementation for s
46330 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f pecialized deplo
46340 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65 6d yments or system
46350 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c 69 s for which SQLi
46360 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 te.** does not p
46370 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 62 6c rovide a suitabl
46380 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
46390 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20 . In this case,
463a0 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 the user.** crea
463b0 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 tes and populate
463c0 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 s an instance of
463d0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 this structure
463e0 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 to pass.** to sq
463f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 lite3_config() a
46400 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 5b 53 long with the [S
46410 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
46420 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 EX] option..** A
46430 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 dditionally, an
46440 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
46450 20 73 74 72 75 63 74 75 72 65 20 63 61 6e 20 62 structure can b
46460 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 e used as an.**
46470 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c 65 20 output variable
46480 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68 when querying th
46490 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 68 65 e system for the
464a0 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a current mutex.*
464b0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
464c0 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c , using the [SQL
464d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
464e0 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a TEX] option..**.
464f0 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 ** The xMutexIni
46500 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 t method defined
46510 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 by this structu
46520 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 re is invoked as
46530 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 .** part of syst
46540 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f em initializatio
46550 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 n by the sqlite3
46560 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 _initialize() fu
46570 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30 nction..** {H170
46580 30 31 7d 20 54 68 65 20 78 4d 75 74 65 78 49 6e 01} The xMutexIn
46590 69 74 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c it routine shall
465a0 20 62 65 20 63 61 6c 6c 65 64 20 62 79 20 53 51 be called by SQ
465b0 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72 20 65 61 Lite once for ea
465c0 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 ch.** effective
465d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
465e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a _initialize()]..
465f0 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 **.** The xMutex
46600 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e End method defin
46610 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 ed by this struc
46620 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 ture is invoked
46630 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 as.** part of sy
46640 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 stem shutdown by
46650 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 the sqlite3_shu
46660 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e tdown() function
46670 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 . The.** impleme
46680 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 ntation of this
46690 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 method is expect
466a0 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c ed to release al
466b0 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a l outstanding.**
466c0 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 resources obtai
466d0 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 ned by the mutex
466e0 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 methods impleme
466f0 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 ntation, especia
46700 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 lly.** those obt
46710 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 ained by the xMu
46720 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 texInit method.
46730 7b 48 31 37 30 30 33 7d 20 54 68 65 20 78 4d 75 {H17003} The xMu
46740 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 texEnd().** inte
46750 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20 69 rface shall be i
46760 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 nvoked once for
46770 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 each call to [sq
46780 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
46790 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d ]..**.** The rem
467a0 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 aining seven met
467b0 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 hods defined by
467c0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 this structure (
467d0 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 xMutexAlloc,.**
467e0 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 xMutexFree, xMut
467f0 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 exEnter, xMutexT
46800 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c ry, xMutexLeave,
46810 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a xMutexHeld and.
46820 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 ** xMutexNotheld
46830 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 ) implement the
46840 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 following interf
46850 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 aces (respective
46860 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ly):.**.** <ul>.
46870 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
46880 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
46890 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
468a0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
468b0 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e ex_free()] </li>
468c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
468d0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
468e0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
468f0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
46900 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e tex_try()] </li>
46910 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
46920 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
46930 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
46940 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
46950 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 tex_held()] </li
46960 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
46970 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
46980 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 eld()] </li>.**
46990 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
469a0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 only difference
469b0 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c is that the publ
469c0 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 ic sqlite3_XXX f
469d0 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 unctions enumera
469e0 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c ted.** above sil
469f0 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 ently ignore any
46a00 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 invocations tha
46a10 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f t pass a NULL po
46a20 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a inter instead.**
46a30 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 of a valid mute
46a40 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d x handle. The im
46a50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
46a60 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 the methods def
46a70 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 ined.** by this
46a80 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f structure are no
46a90 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 t required to ha
46aa0 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 ndle this case,
46ab0 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f the results.** o
46ac0 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c f passing a NULL
46ad0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 pointer instead
46ae0 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 of a valid mute
46af0 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 x handle are und
46b00 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 efined.** (i.e.
46b10 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 it is acceptable
46b20 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 to provide an i
46b30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 mplementation th
46b40 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a at segfaults if.
46b50 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20 ** it is passed
46b60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e a NULL pointer).
46b70 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
46b80 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
46b90 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
46ba0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a _mutex_methods;.
46bb0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
46bc0 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 utex_methods {.
46bd0 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 int (*xMutexIni
46be0 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 t)(void);. int
46bf0 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 (*xMutexEnd)(voi
46c00 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 d);. sqlite3_mu
46c10 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c tex *(*xMutexAll
46c20 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 oc)(int);. void
46c30 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73 (*xMutexFree)(s
46c40 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b qlite3_mutex *);
46c50 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 . void (*xMutex
46c60 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d Enter)(sqlite3_m
46c70 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 utex *);. int (
46c80 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69 *xMutexTry)(sqli
46c90 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 te3_mutex *);.
46ca0 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 void (*xMutexLea
46cb0 76 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ve)(sqlite3_mute
46cc0 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d x *);. int (*xM
46cd0 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69 74 65 utexHeld)(sqlite
46ce0 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 3_mutex *);. in
46cf0 74 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c t (*xMutexNothel
46d00 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 d)(sqlite3_mutex
46d10 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *);.};../*.** C
46d20 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56 API3REF: Mutex V
46d30 65 72 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 erification Rout
46d40 69 6e 65 73 20 7b 48 31 37 30 38 30 7d 20 3c 53 ines {H17080} <S
46d50 32 30 31 33 30 3e 20 3c 53 33 30 38 30 30 3e 0a 20130> <S30800>.
46d60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
46d70 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 3_mutex_held() a
46d80 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nd sqlite3_mutex
46d90 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 _notheld() routi
46da0 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e nes.** are inten
46db0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ded for use insi
46dc0 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 de assert() stat
46dd0 65 6d 65 6e 74 73 2e 20 7b 48 31 37 30 38 31 7d ements. {H17081}
46de0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
46df0 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 .** never uses t
46e00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 hese routines ex
46e10 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 cept inside an a
46e20 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c ssert() and appl
46e30 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 ications.** are
46e40 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f advised to follo
46e50 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 w the lead of th
46e60 65 20 63 6f 72 65 2e 20 20 7b 48 31 37 30 38 32 e core. {H17082
46e70 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a } The core only.
46e80 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c ** provides impl
46e90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 ementations for
46ea0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 these routines w
46eb0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
46ec0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 ed.** with the S
46ed0 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 QLITE_DEBUG flag
46ee0 2e 20 20 7b 41 31 37 30 38 37 7d 20 45 78 74 65 . {A17087} Exte
46ef0 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 rnal mutex imple
46f00 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 mentations.** ar
46f10 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 e only required
46f20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 to provide these
46f30 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c routines if SQL
46f40 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 ITE_DEBUG is.**
46f50 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e defined and if N
46f60 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 DEBUG is not def
46f70 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ined..**.** {H17
46f80 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75 74 69 083} These routi
46f90 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 nes should retur
46fa0 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 n true if the mu
46fb0 74 65 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 tex in their arg
46fc0 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 ument.** is held
46fd0 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 or not held, re
46fe0 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 spectively, by t
46ff0 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
47000 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 d..**.** {X17084
47010 7d 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 } The implementa
47020 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 tion is not requ
47030 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 ired to provided
47040 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 versions of the
47050 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 se.** routines t
47060 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 hat actually wor
47070 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d k. If the implem
47080 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f entation does no
47090 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e t provide workin
470a0 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 g.** versions of
470b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
470c0 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 it should at le
470d0 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 ast provide stub
470e0 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a s that always.**
470f0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 return true so
47100 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f that one does no
47110 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 t get spurious a
47120 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 ssertion failure
47130 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 s..**.** {H17085
47140 7d 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e } If the argumen
47150 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 t to sqlite3_mut
47160 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e ex_held() is a N
47170 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
47180 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 .** the routine
47190 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e should return 1.
471a0 20 20 7b 45 4e 44 7d 20 54 68 69 73 20 73 65 65 {END} This see
471b0 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 ms counter-intui
471c0 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c tive since.** cl
471d0 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 early the mutex
471e0 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 cannot be held i
471f0 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 f it does not ex
47200 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a ist. But the.**
47210 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 the reason the
47220 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 mutex does not e
47230 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20 xist is because
47240 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 the build is not
47250 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 .** using mutexe
47260 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f s. And we do no
47270 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 t want the asser
47280 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 t() containing t
47290 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 he.** call to sq
472a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
472b0 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 () to fail, so a
472c0 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e non-zero return
472d0 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f is.** the appro
472e0 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 priate thing to
472f0 64 6f 2e 20 20 7b 48 31 37 30 38 36 7d 20 54 68 do. {H17086} Th
47300 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
47310 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 notheld().** int
47320 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c erface should al
47330 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e so return 1 when
47340 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f given a NULL po
47350 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 inter..*/.int sq
47360 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
47370 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
47380 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 ;.int sqlite3_mu
47390 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 tex_notheld(sqli
473a0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a te3_mutex*);../*
473b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 .** CAPI3REF: Mu
473c0 74 65 78 20 54 79 70 65 73 20 7b 48 31 37 30 30 tex Types {H1700
473d0 31 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 1} <H17000>.**.*
473e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d * The [sqlite3_m
473f0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e utex_alloc()] in
47400 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 terface takes a
47410 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a single argument.
47420 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 ** which is one
47430 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
47440 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a constants..**.*
47450 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 * The set of sta
47460 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 tic mutexes may
47470 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 change from one
47480 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 SQLite release t
47490 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 o the.** next.
474a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
474b0 74 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 t override the b
474c0 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f uilt-in mutex lo
474d0 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 gic must be.** p
474e0 72 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d repared to accom
474f0 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 modate additiona
47500 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 l static mutexes
47510 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
47520 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 ITE_MUTEX_FAST
47530 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
47540 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
47550 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 X_RECURSIVE
47560 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
47570 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
47580 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 _MASTER 2.#de
47590 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
475a0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 X_STATIC_MEM
475b0 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 3 /* sqlite3
475c0 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 _malloc() */.#de
475d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
475e0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 X_STATIC_MEM2
475f0 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 4 /* sqlite3
47600 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
47610 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
47620 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
47630 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a _PRNG 5 /*
47640 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 sqlite3_random(
47650 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
47660 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
47670 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a _LRU 6 /*
47680 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a lru page list *
47690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
476a0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 _MUTEX_STATIC_LR
476b0 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 U2 7 /* lr
476c0 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a u page list */..
476d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
476e0 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 Retrieve the mut
476f0 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 ex for a databas
47700 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 e connection {H1
47710 37 30 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 7002} <H17000>.*
47720 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
47730 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
47740 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 inter the [sqlit
47750 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 e3_mutex] object
47760 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c that .** serial
47770 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 izes access to t
47780 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
47790 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 nection] given i
477a0 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a n the argument.*
477b0 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 * when the [thre
477c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 ading mode] is S
477d0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 erialized..** If
477e0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
477f0 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d mode] is Single-
47800 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d thread or Multi-
47810 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73 thread then this
47820 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
47830 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
47840 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d er..*/.sqlite3_m
47850 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 utex *sqlite3_db
47860 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29 _mutex(sqlite3*)
47870 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
47880 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e F: Low-Level Con
47890 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 trol Of Database
478a0 20 46 69 6c 65 73 20 7b 48 31 31 33 30 30 7d 20 Files {H11300}
478b0 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b <S30800>.**.** {
478c0 48 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71 6c H11301} The [sql
478d0 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
478e0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d l()] interface m
478f0 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 akes a direct ca
47900 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 ll to the.** xFi
47910 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
47920 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
47930 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
47940 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a ject associated.
47950 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ** with a partic
47960 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 ular database id
47970 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
47980 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
47990 20 7b 48 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a {H11302} The.**
479a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
479b0 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d abase is the nam
479c0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 e assigned to th
479d0 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74 68 e database by th
479e0 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 e.** <a href="la
479f0 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e ng_attach.html">
47a00 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 ATTACH</a> SQL c
47a10 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e ommand that open
47a20 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 ed the.** databa
47a30 73 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f 20 se. {H11303} To
47a40 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e control the main
47a50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
47a60 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 use the name "ma
47a70 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c in".** or a NULL
47a80 20 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33 30 pointer. {H1130
47a90 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 4} The third and
47aa0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
47ab0 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 rs to this routi
47ac0 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 ne.** are passed
47ad0 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 directly throug
47ae0 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 h to the second
47af0 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 and third parame
47b00 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 ters of.** the x
47b10 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
47b20 6f 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 54 68 od. {H11305} Th
47b30 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
47b40 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 f the xFileContr
47b50 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 ol.** method bec
47b60 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 omes the return
47b70 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f value of this ro
47b80 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 utine..**.** {H1
47b90 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 65 63 1306} If the sec
47ba0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a ond parameter (z
47bb0 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 DbName) does not
47bc0 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 match the name
47bd0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 of any.** open d
47be0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 atabase file, th
47bf0 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 en SQLITE_ERROR
47c00 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 48 31 is returned. {H1
47c10 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f 72 1307} This error
47c20 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 .** code is not
47c30 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 remembered and w
47c40 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c ill not be recal
47c50 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f led by [sqlite3_
47c60 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 errcode()].** or
47c70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
47c80 28 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54 68 ()]. {A11308} Th
47c90 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 e underlying xFi
47ca0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
47cb0 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 might.** also r
47cc0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 eturn SQLITE_ERR
47cd0 4f 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 54 68 OR. {A11309} Th
47ce0 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f ere is no way to
47cf0 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 65 74 distinguish bet
47d00 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 ween.** an incor
47d10 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 rect zDbName and
47d20 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 an SQLITE_ERROR
47d30 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 return from the
47d40 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 underlying.** x
47d50 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
47d60 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 od. {END}.**.**
47d70 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 See also: [SQLIT
47d80 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
47d90 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 E].*/.int sqlite
47da0 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 3_file_control(s
47db0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
47dc0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e har *zDbName, in
47dd0 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t op, void*);../
47de0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
47df0 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 esting Interface
47e00 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 30 38 30 {H11400} <S3080
47e10 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
47e20 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
47e30 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 l() interface is
47e40 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 used to read ou
47e50 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 t internal.** st
47e60 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e ate of SQLite an
47e70 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c d to inject faul
47e80 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 ts into SQLite f
47e90 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 or testing.** pu
47ea0 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 69 72 rposes. The fir
47eb0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
47ec0 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 an operation cod
47ed0 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 e that determine
47ee0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c s.** the number,
47ef0 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 meaning, and op
47f00 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 eration of all s
47f10 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 ubsequent parame
47f20 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ters..**.** This
47f30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
47f40 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 t for use by app
47f50 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 lications. It e
47f60 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 xists solely.**
47f70 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 for verifying th
47f80 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 e correct operat
47f90 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
47fa0 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 e library. Depe
47fb0 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 nding.** on how
47fc0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
47fd0 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 ry is compiled,
47fe0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d this interface m
47ff0 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a ight not exist..
48000 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
48010 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 s of the operati
48020 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 on codes, their
48030 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 meanings, the pa
48040 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 rameters.** they
48050 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 take, and what
48060 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 they do are all
48070 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
48080 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 e without notice
48090 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 ..** Unlike most
480a0 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 of the SQLite A
480b0 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f PI, this functio
480c0 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 n is not guarant
480d0 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 eed to.** operat
480e0 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 e consistently f
480f0 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
48100 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
48110 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 int sqlite3_test
48120 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c _control(int op,
48130 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
48140 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 PI3REF: Testing
48150 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 Interface Operat
48160 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 31 ion Codes {H1141
48170 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 0} <H11400>.**.*
48180 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
48190 73 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 s are the valid
481a0 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 operation code p
481b0 61 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a arameters used.*
481c0 2a 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 * as the first a
481d0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
481e0 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
481f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
48200 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
48210 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 their meanings a
48220 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
48230 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 ange.** without
48240 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 notice. These v
48250 61 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 alues are for te
48260 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f sting purposes o
48270 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 nly..** Applicat
48280 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ions should not
48290 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 use any of these
482a0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 parameters or t
482b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 he.** [sqlite3_t
482c0 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 est_control()] i
482d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 nterface..*/.#de
482e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
482f0 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 CTRL_PRNG_SAVE
48300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
48310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
48320 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 ESTCTRL_PRNG_RES
48330 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20 TORE
48340 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
48350 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f E_TESTCTRL_PRNG_
48360 52 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20 RESET
48370 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
48380 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 LITE_TESTCTRL_BI
48390 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 TVEC_TEST
483a0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
483b0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
483c0 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 _FAULT_INSTALL
483d0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
483e0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
483f0 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f TRL_BENIGN_MALLO
48400 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 0a C_HOOKS 10..
48410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
48420 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53 SQLite Runtime S
48430 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c tatus {H17200} <
48440 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60200>.** EXPER
48450 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
48460 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
48470 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
48480 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 runtime status
48490 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 information.** a
484a0 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d bout the preform
484b0 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20 ance of SQLite,
484c0 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 and optionally t
484d0 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a o reset various.
484e0 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 ** highwater mar
484f0 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 ks. The first a
48500 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e rgument is an in
48510 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a teger code for.*
48520 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20 70 * the specific p
48530 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73 arameter to meas
48540 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64 ure. Recognized
48550 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a integer codes.*
48560 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 * are of the for
48570 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53 m [SQLITE_STATUS
48580 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53 _MEMORY_USED | S
48590 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e QLITE_STATUS_...
485a0 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e ]..** The curren
485b0 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70 t value of the p
485c0 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75 arameter is retu
485d0 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72 rned into *pCurr
485e0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68 ent..** The high
485f0 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c est recorded val
48600 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ue is returned i
48610 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20 n *pHighwater.
48620 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 If the.** resetF
48630 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 lag is true, the
48640 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72 65 n the highest re
48650 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 65 cord value is re
48660 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 set after.** *pH
48670 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69 74 ighwater is writ
48680 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65 ten. Some parame
48690 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f ters do not reco
486a0 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a rd the highest.*
486b0 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 * value. For th
486c0 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a ose parameters.*
486d0 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 * nothing is wri
486e0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68 tten into *pHigh
486f0 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 65 water and the re
48700 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72 setFlag is ignor
48710 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72 ed..** Other par
48720 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 6f ameters record o
48730 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 65 nly the highwate
48740 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74 r mark and not t
48750 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61 he current.** va
48760 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 20 lue. For these
48770 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 72 latter parameter
48780 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 s nothing is wri
48790 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72 tten into *pCurr
487a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ent..**.** This
487b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
487c0 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 SQLITE_OK on suc
487d0 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a cess and a non-z
487e0 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f ero.** [error co
487f0 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a de] on failure..
48800 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
48810 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ne is threadsafe
48820 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d but is not atom
48830 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e ic. This routin
48840 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20 e can.** called
48850 77 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65 while other thre
48860 61 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 ads are running
48870 74 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66 the same or diff
48880 65 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 erent SQLite.**
48890 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 interfaces. How
488a0 65 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20 ever the values
488b0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 returned in *pCu
488c0 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 rrent and.** *pH
488d0 69 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74 ighwater reflect
488e0 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53 the status of S
488f0 51 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65 QLite at differe
48900 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d nt points in tim
48910 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70 e.** and it is p
48920 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f ossible that ano
48930 74 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68 ther thread migh
48940 74 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72 t change the par
48950 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 ameter.** in bet
48960 77 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77 ween the times w
48970 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e hen *pCurrent an
48980 64 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72 d *pHighwater ar
48990 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a e written..**.**
489a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
489b0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d te3_db_status()]
489c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 .*/.SQLITE_EXPER
489d0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
489e0 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f te3_status(int o
489f0 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 p, int *pCurrent
48a00 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 , int *pHighwate
48a10 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 r, int resetFlag
48a20 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 );.../*.** CAPI3
48a30 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 REF: Status Para
48a40 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20 meters {H17250}
48a50 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 <H17200>.** EXPE
48a60 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
48a70 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
48a80 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65 stants designate
48a90 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d various run-tim
48aa0 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 e status paramet
48ab0 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 ers.** that can
48ac0 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b be returned by [
48ad0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
48ae0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a ]..**.** <dl>.**
48af0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
48b00 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f US_MEMORY_USED</
48b10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
48b20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
48b30 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 current amount
48b40 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 of memory checke
48b50 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b d out.** using [
48b60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
48b70 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74 ], either direct
48b80 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 ly or indirectly
48b90 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 . The.** figure
48ba0 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 includes calls
48bb0 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 made to [sqlite3
48bc0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 _malloc()] by th
48bd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
48be0 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 and internal me
48bf0 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68 mory usage by th
48c00 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
48c10 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 . Scratch memor
48c20 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 y.** controlled
48c30 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
48c40 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61 G_SCRATCH] and a
48c50 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61 uxiliary page-ca
48c60 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f che.** memory co
48c70 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c ntrolled by [SQL
48c80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
48c90 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 ACHE] is not inc
48ca0 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 luded in.** this
48cb0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 parameter. The
48cc0 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 amount returned
48cd0 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74 is the sum of t
48ce0 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a he allocation.**
48cf0 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74 sizes as report
48d00 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20 ed by the xSize
48d10 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 method in [sqlit
48d20 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e e3_mem_methods].
48d30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
48d40 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 SQLITE_STATUS_MA
48d50 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a LLOC_SIZE</dt>.*
48d60 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
48d70 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 eter records the
48d80 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 largest memory
48d90 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
48da0 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 st.** handed to
48db0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
48dc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
48dd0 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 ealloc()] (or th
48de0 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 eir.** internal
48df0 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f equivalents). O
48e00 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 nly the value re
48e10 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a turned in the.**
48e20 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 *pHighwater par
48e30 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
48e40 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 e3_status()] is
48e50 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a of interest. .*
48e60 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 * The value writ
48e70 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 ten into the *pC
48e80 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 urrent parameter
48e90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f is undefined.</
48ea0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
48eb0 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
48ec0 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a CACHE_USED</dt>.
48ed0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
48ee0 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 meter returns th
48ef0 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
48f00 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 s used out of th
48f10 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20 e.** [pagecache
48f20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
48f30 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69 ] that was confi
48f40 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20 gured using .**
48f50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
48f60 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a AGECACHE]. The.
48f70 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ** value returne
48f80 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e d is in pages, n
48f90 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 ot in bytes.</dd
48fa0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
48fb0 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 TE_STATUS_PAGECA
48fc0 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 CHE_OVERFLOW</dt
48fd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
48fe0 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 rameter returns
48ff0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
49000 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68 tes of page cach
49010 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e.** allocation
49020 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 which could not
49030 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79 be statisfied by
49040 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
49050 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a FIG_PAGECACHE].*
49060 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 * buffer and whe
49070 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 re forced to ove
49080 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 rflow to [sqlite
49090 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 3_malloc()]. Th
490a0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61 e.** returned va
490b0 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c lue includes all
490c0 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 ocations that ov
490d0 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 erflowed because
490e0 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74 they.** where t
490f0 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77 oo large (they w
49100 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 ere larger than
49110 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74 the "sz" paramet
49120 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 er to.** [SQLITE
49130 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
49140 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69 E]) and allocati
49150 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f ons that overflo
49160 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e wed because.** n
49170 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74 o space was left
49180 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 in the page cac
49190 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c he.</dd>.**.** <
491a0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
491b0 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c _PAGECACHE_SIZE<
491c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
491d0 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 parameter recor
491e0 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d ds the largest m
491f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
49200 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 request.** hand
49210 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65 ed to [pagecache
49220 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
49230 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 r]. Only the va
49240 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 lue returned in
49250 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 the.** *pHighwat
49260 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 er parameter to
49270 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
49280 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 )] is of interes
49290 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 t. .** The valu
492a0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 e written into t
492b0 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 he *pCurrent par
492c0 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 ameter is undefi
492d0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
492e0 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
492f0 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f S_SCRATCH_USED</
49300 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
49310 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
49320 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
49330 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64 allocations used
49340 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b out of the.** [
49350 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 scratch memory a
49360 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
49370 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 ured using.** [S
49380 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
49390 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75 ATCH]. The valu
493a0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e e returned is in
493b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f allocations, no
493c0 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20 t.** in bytes.
493d0 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74 Since a single t
493e0 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68 hread may only h
493f0 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20 ave one scratch
49400 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 allocation.** ou
49410 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d tstanding at tim
49420 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 e, this paramete
49430 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74 r also reports t
49440 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 he number of thr
49450 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63 eads.** using sc
49460 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20 ratch memory at
49470 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f the same time.</
49480 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
49490 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 LITE_STATUS_SCRA
494a0 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 TCH_OVERFLOW</dt
494b0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
494c0 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 rameter returns
494d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
494e0 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d tes of scratch m
494f0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
49500 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 ion which could
49510 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 not be statisfie
49520 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 d by the [SQLITE
49530 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
49540 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 .** buffer and w
49550 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f here forced to o
49560 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 verflow to [sqli
49570 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 te3_malloc()].
49580 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65 The values.** re
49590 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f turned include o
495a0 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65 verflows because
495b0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 the requested a
495c0 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f llocation was to
495d0 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61 o.** larger (tha
495e0 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68 t is, because th
495f0 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f e requested allo
49600 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65 cation was large
49610 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73 r than the.** "s
49620 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 z" parameter to
49630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
49640 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63 CRATCH]) and bec
49650 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20 ause no scratch
49660 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 buffer.** slots
49670 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a were available..
49680 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ** </dd>.**.** <
49690 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
496a0 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64 _SCRATCH_SIZE</d
496b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
496c0 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 arameter records
496d0 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d the largest mem
496e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
496f0 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 equest.** handed
49700 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d to [scratch mem
49710 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 ory allocator].
49720 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 Only the value
49730 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a returned in the.
49740 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 ** *pHighwater p
49750 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
49760 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 ite3_status()] i
49770 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 s of interest.
49780 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 .** The value wr
49790 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a itten into the *
497a0 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 pCurrent paramet
497b0 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e er is undefined.
497c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
497d0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 SQLITE_STATUS_PA
497e0 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a RSER_STACK</dt>.
497f0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
49800 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 meter records th
49810 65 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72 e deepest parser
49820 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f stack. It is o
49830 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 nly.** meaningfu
49840 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 l if SQLite is c
49850 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59 ompiled with [YY
49860 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50 TRACKMAXSTACKDEP
49870 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 TH].</dd>.** </d
49880 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 l>.**.** New sta
49890 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d tus parameters m
498a0 61 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d ay be added from
498b0 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a time to time..*
498c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
498d0 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 _STATUS_MEMORY_U
498e0 53 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23 SED 0.#
498f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
49900 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 ATUS_PAGECACHE_U
49910 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66 SED 1.#def
49920 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
49930 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 S_PAGECACHE_OVER
49940 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65 FLOW 2.#define
49950 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 SQLITE_STATUS_S
49960 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20 CRATCH_USED
49970 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
49980 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 LITE_STATUS_SCRA
49990 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20 TCH_OVERFLOW
499a0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
499b0 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f E_STATUS_MALLOC_
499c0 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a SIZE 5.
499d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
499e0 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 TATUS_PARSER_STA
499f0 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 CK 6.#de
49a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
49a10 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a US_PAGECACHE_SIZ
49a20 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e E 7.#defin
49a30 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
49a40 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20 SCRATCH_SIZE
49a50 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 8../*.** CA
49a60 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
49a70 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74 Connection Stat
49a80 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30 us {H17500} <S60
49a90 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 200>.** EXPERIME
49aa0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 NTAL.**.** This
49ab0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
49ac0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 d to retrieve ru
49ad0 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 ntime status inf
49ae0 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f ormation .** abo
49af0 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74 ut a single [dat
49b00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
49b10 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 ]. The first ar
49b20 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
49b30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
49b40 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62 tion object to b
49b50 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 e interrogated.
49b60 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
49b70 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70 ment.** is the p
49b80 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65 arameter to inte
49b90 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e rrogate. Curren
49ba0 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c tly, the only al
49bb0 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66 lowed value.** f
49bc0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 or the second pa
49bd0 72 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49 rameter is [SQLI
49be0 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b TE_DBSTATUS_LOOK
49bf0 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 ASIDE_USED]..**
49c00 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f Additional optio
49c10 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 ns will likely a
49c20 70 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 20 ppear in future
49c30 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
49c40 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 te..**.** The cu
49c50 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 rrent value of t
49c60 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 72 he requested par
49c70 61 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 65 ameter is writte
49c80 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 n into *pCur.**
49c90 61 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 20 and the highest
49ca0 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 instantaneous va
49cb0 6c 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 lue is written i
49cc0 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66 nto *pHiwtr. If
49cd0 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67 .** the resetFlg
49ce0 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 is true, then t
49cf0 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 he highest insta
49d00 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 ntaneous value i
49d10 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20 s.** reset back
49d20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72 down to the curr
49d30 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a ent value..**.**
49d40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
49d50 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e te3_status()] an
49d60 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f d [sqlite3_stmt_
49d70 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 status()]..*/.SQ
49d80 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
49d90 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 L int sqlite3_db
49da0 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a _status(sqlite3*
49db0 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 , int op, int *p
49dc0 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72 Cur, int *pHiwtr
49dd0 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b , int resetFlg);
49de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
49df0 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 : Status Paramet
49e00 65 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 65 ers for database
49e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31 connections {H1
49e20 37 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 7520} <H17500>.*
49e30 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
49e40 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72 62 *.** Status verb
49e50 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64 s for [sqlite3_d
49e60 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a b_status()]..**.
49e70 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
49e80 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c QLITE_DBSTATUS_L
49e90 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f 64 OOKASIDE_USED</d
49ea0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
49eb0 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
49ec0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6c the number of l
49ed0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
49ee0 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 0a slots currently.
49ef0 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e 3c ** checked out.<
49f00 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f /dd>.** </dl>.*/
49f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
49f20 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 DBSTATUS_LOOKASI
49f30 44 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a 0a DE_USED 0...
49f40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
49f50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
49f60 6e 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 35 nt Status {H1755
49f70 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 0} <S60200>.** E
49f80 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
49f90 2a 20 45 61 63 68 20 70 72 65 70 61 72 65 64 20 * Each prepared
49fa0 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 61 statement mainta
49fb0 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 5b ins various.** [
49fc0 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 SQLITE_STMTSTATU
49fd0 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 S_SORT | counter
49fe0 73 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 20 s] that measure
49ff0 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 the number.** of
4a000 20 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 65 times it has pe
4a010 72 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 63 rformed specific
4a020 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 68 operations. Th
4a030 65 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 6e ese counters can
4a040 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 6d .** be used to m
4a050 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 6f onitor the perfo
4a060 72 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 72 rmance character
4a070 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 72 istics of the pr
4a080 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
4a090 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 ents. For examp
4a0a0 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 65 le, if the numbe
4a0b0 72 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 73 r of table steps
4a0c0 20 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 73 greatly exceeds
4a0d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
4a0e0 66 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 73 f table searches
4a0f0 20 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 2c or result rows,
4a100 20 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e 64 that would tend
4a110 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a 20 to indicate.**
4a120 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 that the prepare
4a130 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75 d statement is u
4a140 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 6c sing a full tabl
4a150 65 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 68 e scan rather th
4a160 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e 20 an.** an index.
4a170 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 .**.** This int
4a180 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
4a190 6f 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 72 o retrieve and r
4a1a0 65 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 6c eset counter val
4a1b0 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 ues from.** a [p
4a1c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
4a1d0 74 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 t]. The first a
4a1e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 70 rgument is the p
4a1f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
4a200 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 62 t.** object to b
4a210 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 e interrogated.
4a220 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
4a230 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e ment.** is an in
4a240 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 61 teger code for a
4a250 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54 specific [SQLIT
4a260 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 E_STMTSTATUS_SOR
4a270 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 T | counter].**
4a280 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 to be interrogat
4a290 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 72 ed. .** The curr
4a2a0 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 ent value of the
4a2b0 20 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e 74 requested count
4a2c0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
4a2d0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 46 ** If the resetF
4a2e0 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e lg is true, then
4a2f0 20 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 20 the counter is
4a300 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 66 reset to zero af
4a310 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 ter this.** inte
4a320 72 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 72 rface call retur
4a330 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ns..**.** See al
4a340 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 so: [sqlite3_sta
4a350 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tus()] and [sqli
4a360 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d te3_db_status()]
4a370 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 ..*/.SQLITE_EXPE
4a380 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
4a390 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 ite3_stmt_status
4a3a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
4a3b0 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 74 int op,int reset
4a3c0 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Flg);../*.** CAP
4a3d0 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 I3REF: Status Pa
4a3e0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 65 rameters for pre
4a3f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
4a400 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 35 {H17570} <H1755
4a410 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
4a420 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 AL.**.** These p
4a430 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
4a440 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 os define intege
4a450 72 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 6d r codes that nam
4a460 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 6c e counter.** val
4a470 75 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 ues associated w
4a480 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ith the [sqlite3
4a490 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 20 _stmt_status()]
4a4a0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 interface..** Th
4a4b0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 e meanings of th
4a4c0 65 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 65 e various counte
4a4d0 72 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 rs are as follow
4a4e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a s:.**.** <dl>.**
4a4f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 <dt>SQLITE_STMT
4a500 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f STATUS_FULLSCAN_
4a510 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 STEP</dt>.** <dd
4a520 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d >This is the num
4a530 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 ber of times tha
4a540 74 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 65 t SQLite has ste
4a550 70 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e 0a pped forward in.
4a560 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 61 ** a table as pa
4a570 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 62 rt of a full tab
4a580 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 20 le scan. Large
4a590 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 73 numbers for this
4a5a0 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 counter.** may
4a5b0 69 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 75 indicate opportu
4a5c0 6e 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 6f nities for perfo
4a5d0 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65 rmance improveme
4a5e0 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63 nt through .** c
4a5f0 61 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e areful use of in
4a600 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a dices.</dd>.**.*
4a610 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d * <dt>SQLITE_STM
4a620 54 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 74 TSTATUS_SORT</dt
4a630 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 73 >.** <dd>This is
4a640 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 the number of s
4a650 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 ort operations t
4a660 68 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 65 hat have occurre
4a670 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f d..** A non-zero
4a680 20 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 63 value in this c
4a690 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 63 ounter may indic
4a6a0 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 ate an opportuni
4a6b0 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 ty to.** improve
4a6c0 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 65 ment performance
4a6d0 20 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 6c through careful
4a6e0 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e use of indices.
4a6f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c </dd>.**.** </dl
4a700 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
4a710 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 ITE_STMTSTATUS_F
4a720 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 20 ULLSCAN_STEP
4a730 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
4a740 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 E_STMTSTATUS_SOR
4a750 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 T 2
4a760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4a770 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 61 : Custom Page Ca
4a780 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 che Object.** EX
4a790 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
4a7a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 The sqlite3_pca
4a7b0 63 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 71 che type is opaq
4a7c0 75 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c 65 ue. It is imple
4a7d0 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 65 mented by.** the
4a7e0 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 6c pluggable modul
4a7f0 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 e. The SQLite c
4a800 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c ore has no knowl
4a810 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 73 edge of.** its s
4a820 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c 20 ize or internal
4a830 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e 65 structure and ne
4a840 76 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 74 ver deals with t
4a850 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 63 he.** sqlite3_pc
4a860 61 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 65 ache object exce
4a870 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 6e pt by holding an
4a880 64 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 65 d passing pointe
4a890 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 6a rs.** to the obj
4a8a0 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b ect..**.** See [
4a8b0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
4a8c0 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 69 ethods] for addi
4a8d0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
4a8e0 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 on..*/.typedef s
4a8f0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 truct sqlite3_pc
4a900 61 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 ache sqlite3_pca
4a910 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 che;../*.** CAPI
4a920 33 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 6f 3REF: Applicatio
4a930 6e 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 43 n Defined Page C
4a940 61 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 4d ache..** EXPERIM
4a950 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ENTAL.**.** The
4a960 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
4a970 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
4a980 50 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e PCACHE], ...) in
4a990 74 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 72 terface can.** r
4a9a0 65 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 72 egister an alter
4a9b0 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68 native page cach
4a9c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
4a9d0 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 by passing in a
4a9e0 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f n .** instance o
4a9f0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 f the sqlite3_pc
4aa00 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 72 ache_methods str
4aa10 75 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a 6f ucture. The majo
4aa20 72 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 rity of the .**
4aa30 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 64 heap memory used
4aa40 20 62 79 20 73 71 6c 69 74 65 20 69 73 20 75 73 by sqlite is us
4aa50 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 ed by the page c
4aa60 61 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 61 ache to cache da
4aa70 74 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f 6d ta read .** from
4aa80 2c 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 65 , or ready to be
4aa90 20 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 65 written to, the
4aaa0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 database file.
4aab0 42 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 By implementing
4aac0 61 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 67 a .** custom pag
4aad0 65 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 68 e cache using th
4aae0 69 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c 69 is API, an appli
4aaf0 63 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 cation can contr
4ab00 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 63 ol more .** prec
4ab10 69 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e 74 isely the amount
4ab20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 of memory consu
4ab30 6d 65 64 20 62 79 20 73 71 6c 69 74 65 2c 20 74 med by sqlite, t
4ab40 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 he way in which
4ab50 0a 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 20 .** said memory
4ab60 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64 is allocated and
4ab70 20 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 74 released, and t
4ab80 68 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 64 he policies used
4ab90 20 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e to .** determin
4aba0 65 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 20 e exactly which
4abb0 70 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 62 parts of a datab
4abc0 61 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 63 ase file are cac
4abd0 68 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 hed and for .**
4abe0 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 how long..**.**
4abf0 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 The contents of
4ac00 74 68 65 20 73 74 72 75 63 74 75 72 65 20 61 72 the structure ar
4ac10 65 20 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 69 e copied to an i
4ac20 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 nternal buffer b
4ac30 79 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 68 y sqlite.** with
4ac40 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b in the call to [
4ac50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e sqlite3_config].
4ac60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
4ac70 28 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c () method is cal
4ac80 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 led once for eac
4ac90 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 h call to [sqlit
4aca0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
4acb0 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c .** (usually onl
4acc0 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 68 y once during th
4acd0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 e lifetime of th
4ace0 65 20 70 72 6f 63 65 73 73 29 2e 20 49 74 20 69 e process). It i
4acf0 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f s passed.** a co
4ad00 70 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 py of the sqlite
4ad10 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
4ad20 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 49 74 20 .pArg value. It
4ad30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 can be used to s
4ad40 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20 et.** up global
4ad50 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 6d structures and m
4ad60 75 74 65 78 65 73 20 72 65 71 75 69 72 65 64 20 utexes required
4ad70 62 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 61 by the custom pa
4ad80 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70 ge cache .** imp
4ad90 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65 lementation. The
4ada0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 xShutdown() met
4adb0 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72 hod is called fr
4adc0 6f 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 om within .** [s
4add0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
4ade0 29 5d 2c 20 69 66 20 74 68 65 20 61 70 70 6c 69 )], if the appli
4adf0 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 cation invokes t
4ae00 68 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20 his API. It can
4ae10 62 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 6c be used.** to cl
4ae20 65 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 74 ean up any outst
4ae30 61 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73 anding resources
4ae40 20 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20 before process
4ae50 73 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 shutdown, if req
4ae60 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
4ae70 20 78 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f xCreate() metho
4ae80 64 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e d is used to con
4ae90 73 74 72 75 63 74 20 61 20 6e 65 77 20 63 61 63 struct a new cac
4aea0 68 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 65 he instance. The
4aeb0 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 .** first parame
4aec0 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 20 ter, szPage, is
4aed0 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 the size in byte
4aee0 73 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 74 s of the pages t
4aef0 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 hat must.** be a
4af00 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 llocated by the
4af10 63 61 63 68 65 2e 20 73 7a 50 61 67 65 20 77 69 cache. szPage wi
4af20 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 65 ll not be a powe
4af30 72 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a 2a r of two. The.**
4af40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
4af50 2c 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73 , bPurgeable, is
4af60 20 74 72 75 65 20 69 66 20 74 68 65 20 63 61 63 true if the cac
4af70 68 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 he being created
4af80 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 will.** be used
4af90 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 to cache databa
4afa0 73 65 20 70 61 67 65 73 20 72 65 61 64 20 66 72 se pages read fr
4afb0 6f 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 65 64 om a file stored
4afc0 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 on disk, or.**
4afd0 66 61 6c 73 65 20 69 66 20 69 74 20 69 73 20 75 false if it is u
4afe0 73 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 sed for an in-me
4aff0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2e 20 54 mory database. T
4b000 68 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 he cache impleme
4b010 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 ntation.** does
4b020 6e 6f 74 20 68 61 76 65 20 74 6f 20 64 6f 20 61 not have to do a
4b030 6e 79 74 68 69 6e 67 20 73 70 65 63 69 61 6c 20 nything special
4b040 62 61 73 65 64 20 6f 6e 20 74 68 65 20 76 61 6c based on the val
4b050 75 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c 65 ue of bPurgeable
4b060 2c 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 6c ,.** it is purel
4b070 79 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a y advisory. .**.
4b080 2a 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 7a ** The xCachesiz
4b090 65 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 e() method may b
4b0a0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 e called at any
4b0b0 74 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 74 time by SQLite t
4b0c0 6f 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 67 o set the.** sug
4b0d0 67 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 63 gested maximum c
4b0e0 61 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 65 ache-size (numbe
4b0f0 72 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 65 r of pages store
4b100 64 20 62 79 29 20 74 68 65 20 63 61 63 68 65 0a d by) the cache.
4b110 2a 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 73 ** instance pass
4b120 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
4b130 61 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 69 argument. This i
4b140 73 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e 66 s the value conf
4b150 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 igured using.**
4b160 74 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 41 the SQLite "[PRA
4b170 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 22 GMA cache_size]"
4b180 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 74 command. As wit
4b190 68 20 74 68 65 20 62 50 75 72 67 65 61 62 6c 65 h the bPurgeable
4b1a0 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 74 parameter,.** t
4b1b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
4b1c0 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 n is not require
4b1d0 64 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 d to do anything
4b1e0 20 73 70 65 63 69 61 6c 20 77 69 74 68 20 74 68 special with th
4b1f0 69 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 74 20 is.** value, it
4b200 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 is advisory only
4b210 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67 ..**.** The xPag
4b220 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f 64 20 ecount() method
4b230 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
4b240 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
4b250 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 s currently.** s
4b260 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 61 63 tored in the cac
4b270 68 65 20 73 75 70 70 6c 69 65 64 20 61 73 20 61 he supplied as a
4b280 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 0a n argument..** .
4b290 2a 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 20 ** The xFetch()
4b2a0 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 method is used t
4b2b0 6f 20 66 65 74 63 68 20 61 20 70 61 67 65 20 61 o fetch a page a
4b2c0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e nd return a poin
4b2d0 74 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 41 ter to it. .** A
4b2e0 20 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 73 'page', in this
4b2f0 20 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 62 context, is a b
4b300 75 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 20 uffer of szPage
4b310 62 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 74 bytes aligned at
4b320 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 6f an.** 8-byte bo
4b330 75 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 65 undary. The page
4b340 20 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 69 to be fetched i
4b350 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 s determined by
4b360 74 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a 20 the key. The.**
4b370 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c 75 mimimum key valu
4b380 65 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 74 e is 1. After it
4b390 20 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 65 has been retrie
4b3a0 76 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 68 ved using xFetch
4b3b0 2c 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 69 , the page .** i
4b3c0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 s considered to
4b3d0 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a be pinned..**.**
4b3e0 20 49 66 20 74 68 65 20 72 65 71 75 65 73 74 65 If the requeste
4b3f0 64 20 70 61 67 65 20 69 73 20 61 6c 72 65 61 64 d page is alread
4b400 79 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 y in the page ca
4b410 63 68 65 2c 20 74 68 65 6e 20 61 20 70 6f 69 6e che, then a poin
4b420 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 61 ter to.** the ca
4b430 63 68 65 64 20 62 75 66 66 65 72 20 73 68 6f 75 ched buffer shou
4b440 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 20 77 ld be returned w
4b450 69 74 68 20 69 74 73 20 63 6f 6e 74 65 6e 74 73 ith its contents
4b460 20 69 6e 74 61 63 74 2e 20 49 66 20 74 68 65 0a intact. If the.
4b470 2a 2a 20 70 61 67 65 20 69 73 20 6e 6f 74 20 61 ** page is not a
4b480 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 63 61 lready in the ca
4b490 63 68 65 2c 20 74 68 65 6e 20 74 68 65 20 65 78 che, then the ex
4b4a0 70 65 63 74 65 64 20 62 65 68 61 76 69 6f 75 72 pected behaviour
4b4b0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 61 63 68 65 of the.** cache
4b4c0 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 is determined b
4b4d0 79 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 y the value of t
4b4e0 68 65 20 63 72 65 61 74 65 46 6c 61 67 20 70 61 he createFlag pa
4b4f0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 0a 2a rameter passed.*
4b500 2a 20 74 6f 20 78 46 65 74 63 68 2c 20 61 63 63 * to xFetch, acc
4b510 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 66 6f ording to the fo
4b520 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a 0a 2a llowing table:.*
4b530 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 *.** <table bord
4b540 65 72 3d 31 20 77 69 64 74 68 3d 38 35 25 20 61 er=1 width=85% a
4b550 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a 20 lign=center>.**
4b560 20 20 3c 74 72 3e 3c 74 68 3e 63 72 65 61 74 65 <tr><th>create
4b570 46 6c 61 67 3c 74 68 3e 45 78 70 65 63 74 65 64 Flag<th>Expected
4b580 20 42 65 68 61 76 69 6f 75 72 0a 2a 2a 20 20 20 Behaviour.**
4b590 3c 74 72 3e 3c 74 64 3e 30 3c 74 64 3e 4e 55 4c <tr><td>0<td>NUL
4b5a0 4c 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 L should be retu
4b5b0 72 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 63 61 63 rned. No new cac
4b5c0 68 65 20 65 6e 74 72 79 20 69 73 20 63 72 65 61 he entry is crea
4b5d0 74 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 ted..** <tr><t
4b5e0 64 3e 31 3c 74 64 3e 49 66 20 63 72 65 61 74 65 d>1<td>If create
4b5f0 46 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 31 Flag is set to 1
4b600 2c 20 74 68 69 73 20 69 6e 64 69 63 61 74 65 73 , this indicates
4b610 20 74 68 61 74 20 0a 2a 2a 20 20 20 20 20 20 20 that .**
4b620 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 SQLite
4b630 69 73 20 68 6f 6c 64 69 6e 67 20 70 69 6e 6e 65 is holding pinne
4b640 64 20 70 61 67 65 73 20 74 68 61 74 20 63 61 6e d pages that can
4b650 20 62 65 20 75 6e 70 69 6e 6e 65 64 0a 2a 2a 20 be unpinned.**
4b660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 62 b
4b670 79 20 77 72 69 74 69 6e 67 20 74 68 65 69 72 20 y writing their
4b680 63 6f 6e 74 65 6e 74 73 20 74 6f 20 74 68 65 20 contents to the
4b690 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 28 61 database file (a
4b6a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
4b6b0 20 20 20 72 65 6c 61 74 69 76 65 6c 79 20 65 78 relatively ex
4b6c0 70 65 6e 73 69 76 65 20 6f 70 65 72 61 74 69 6f pensive operatio
4b6d0 6e 29 2e 20 49 6e 20 74 68 69 73 20 73 69 74 75 n). In this situ
4b6e0 61 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 ation the.**
4b6f0 20 20 20 20 20 20 20 20 20 20 20 20 63 61 63 68 cach
4b700 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
4b710 20 68 61 73 20 74 77 6f 20 63 68 6f 69 63 65 73 has two choices
4b720 3a 20 69 74 20 63 61 6e 20 72 65 74 75 72 6e 20 : it can return
4b730 4e 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 NULL,.**
4b740 20 20 20 20 20 20 20 20 69 6e 20 77 68 69 63 68 in which
4b750 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c case SQLite wil
4b760 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 75 6e 70 l attempt to unp
4b770 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a in one or more .
4b780 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
4b790 20 20 70 61 67 65 73 20 62 65 66 6f 72 65 20 72 pages before r
4b7a0 65 2d 72 65 71 75 65 73 74 69 6e 67 20 74 68 65 e-requesting the
4b7b0 20 73 61 6d 65 20 70 61 67 65 2c 20 6f 72 20 69 same page, or i
4b7c0 74 20 63 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 t can.**
4b7d0 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 allocate
4b7e0 20 61 20 6e 65 77 20 70 61 67 65 20 61 6e 64 20 a new page and
4b7f0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 return a pointer
4b800 20 74 6f 20 69 74 2e 20 49 66 20 61 20 6e 65 77 to it. If a new
4b810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
4b820 20 20 20 70 61 67 65 20 69 73 20 61 6c 6c 6f 63 page is alloc
4b830 61 74 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 75 ated, then it mu
4b840 73 74 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 st be completely
4b850 20 7a 65 72 6f 65 64 20 62 65 66 6f 72 65 20 0a zeroed before .
4b860 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
4b870 20 20 69 74 20 69 73 20 72 65 74 75 72 6e 65 64 it is returned
4b880 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64 3e 32 ..** <tr><td>2
4b890 3c 74 64 3e 49 66 20 63 72 65 61 74 65 46 6c 61 <td>If createFla
4b8a0 67 20 69 73 20 73 65 74 20 74 6f 20 32 2c 20 74 g is set to 2, t
4b8b0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 6e 6f hen SQLite is no
4b8c0 74 20 68 6f 6c 64 69 6e 67 20 61 6e 79 0a 2a 2a t holding any.**
4b8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4b8e0 70 69 6e 6e 65 64 20 70 61 67 65 73 20 61 73 73 pinned pages ass
4b8f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
4b900 20 73 70 65 63 69 66 69 63 20 63 61 63 68 65 20 specific cache
4b910 70 61 73 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 passed.**
4b920 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 as the
4b930 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
4b940 6f 20 78 46 65 74 63 68 28 29 20 74 68 61 74 20 o xFetch() that
4b950 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 2e can be unpinned.
4b960 20 54 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 The.**
4b970 20 20 20 20 20 20 20 63 61 63 68 65 20 69 6d 70 cache imp
4b980 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
4b990 6c 64 20 61 74 74 65 6d 70 74 20 74 6f 20 61 6c ld attempt to al
4b9a0 6c 6f 63 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 locate a new.**
4b9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 63 c
4b9c0 61 63 68 65 20 65 6e 74 72 79 20 61 6e 64 20 72 ache entry and r
4b9d0 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 eturn a pointer
4b9e0 74 6f 20 69 74 2e 20 41 67 61 69 6e 2c 20 74 68 to it. Again, th
4b9f0 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 e new.**
4ba00 20 20 20 20 20 20 20 20 70 61 67 65 20 73 68 6f page sho
4ba10 75 6c 64 20 62 65 20 7a 65 72 6f 65 64 20 62 65 uld be zeroed be
4ba20 66 6f 72 65 20 69 74 20 69 73 20 72 65 74 75 72 fore it is retur
4ba30 6e 65 64 2e 20 49 66 20 74 68 65 20 78 46 65 74 ned. If the xFet
4ba40 63 68 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 ch().**
4ba50 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 72 65 method re
4ba60 74 75 72 6e 73 20 4e 55 4c 4c 20 77 68 65 6e 20 turns NULL when
4ba70 63 72 65 61 74 65 46 6c 61 67 3d 3d 32 2c 20 53 createFlag==2, S
4ba80 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
4ba90 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 at.**
4baa0 20 20 20 20 20 61 20 6d 65 6d 6f 72 79 20 61 6c a memory al
4bab0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 20 location failed
4bac0 61 6e 64 20 72 65 74 75 72 6e 73 20 53 51 4c 49 and returns SQLI
4bad0 54 45 5f 4e 4f 4d 45 4d 20 74 6f 20 74 68 65 0a TE_NOMEM to the.
4bae0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
4baf0 20 20 75 73 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 user..** </tab
4bb00 6c 65 3e 0a 2a 2a 0a 2a 2a 20 78 55 6e 70 69 6e le>.**.** xUnpin
4bb10 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 () is called by
4bb20 53 51 4c 69 74 65 20 77 69 74 68 20 61 20 70 6f SQLite with a po
4bb30 69 6e 74 65 72 20 74 6f 20 61 20 63 75 72 72 65 inter to a curre
4bb40 6e 74 6c 79 20 70 69 6e 6e 65 64 20 70 61 67 65 ntly pinned page
4bb50 0a 2a 2a 20 61 73 20 69 74 73 20 73 65 63 6f 6e .** as its secon
4bb60 64 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 74 d argument. If t
4bb70 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
4bb80 65 72 2c 20 64 69 73 63 61 72 64 2c 20 69 73 20 er, discard, is
4bb90 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 non-zero,.** the
4bba0 6e 20 74 68 65 20 70 61 67 65 20 73 68 6f 75 6c n the page shoul
4bbb0 64 20 62 65 20 65 76 69 63 74 65 64 20 66 72 6f d be evicted fro
4bbc0 6d 20 74 68 65 20 63 61 63 68 65 2e 20 49 6e 20 m the cache. In
4bbd0 74 68 69 73 20 63 61 73 65 20 53 51 4c 69 74 65 this case SQLite
4bbe0 20 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 .** assumes tha
4bbf0 74 20 74 68 65 20 6e 65 78 74 20 74 69 6d 65 20 t the next time
4bc00 74 68 65 20 70 61 67 65 20 69 73 20 72 65 74 72 the page is retr
4bc10 69 65 76 65 64 20 66 72 6f 6d 20 74 68 65 20 63 ieved from the c
4bc20 61 63 68 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 ache using.** th
4bc30 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f e xFetch() metho
4bc40 64 2c 20 69 74 20 77 69 6c 6c 20 62 65 20 7a 65 d, it will be ze
4bc50 72 6f 65 64 2e 20 49 66 20 74 68 65 20 64 69 73 roed. If the dis
4bc60 63 61 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 card parameter i
4bc70 73 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 65 6e 20 s.** zero, then
4bc80 74 68 65 20 70 61 67 65 20 69 73 20 63 6f 6e 73 the page is cons
4bc90 69 64 65 72 65 64 20 74 6f 20 62 65 20 75 6e 70 idered to be unp
4bca0 69 6e 6e 65 64 2e 20 54 68 65 20 63 61 63 68 65 inned. The cache
4bcb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
4bcc0 2a 2a 20 6d 61 79 20 63 68 6f 6f 73 65 20 74 6f ** may choose to
4bcd0 20 72 65 63 6c 61 69 6d 20 28 66 72 65 65 20 6f reclaim (free o
4bce0 72 20 72 65 63 79 63 6c 65 29 20 75 6e 70 69 6e r recycle) unpin
4bcf0 6e 65 64 20 70 61 67 65 73 20 61 74 20 61 6e 79 ned pages at any
4bd00 20 74 69 6d 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 time..** SQLite
4bd10 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 6e 65 assumes that ne
4bd20 78 74 20 74 69 6d 65 20 74 68 65 20 70 61 67 65 xt time the page
4bd30 20 69 73 20 72 65 74 72 69 65 76 65 64 20 66 72 is retrieved fr
4bd40 6f 6d 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 om the cache.**
4bd50 69 74 20 77 69 6c 6c 20 65 69 74 68 65 72 20 62 it will either b
4bd60 65 20 7a 65 72 6f 65 64 2c 20 6f 72 20 63 6f 6e e zeroed, or con
4bd70 74 61 69 6e 20 74 68 65 20 73 61 6d 65 20 64 61 tain the same da
4bd80 74 61 20 74 68 61 74 20 69 74 20 64 69 64 20 77 ta that it did w
4bd90 68 65 6e 20 69 74 0a 2a 2a 20 77 61 73 20 75 6e hen it.** was un
4bda0 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 pinned..**.** Th
4bdb0 65 20 63 61 63 68 65 20 69 73 20 6e 6f 74 20 72 e cache is not r
4bdc0 65 71 75 69 72 65 64 20 74 6f 20 70 65 72 66 6f equired to perfo
4bdd0 72 6d 20 61 6e 79 20 72 65 66 65 72 65 6e 63 65 rm any reference
4bde0 20 63 6f 75 6e 74 69 6e 67 2e 20 41 20 73 69 6e counting. A sin
4bdf0 67 6c 65 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 gle .** call to
4be00 78 55 6e 70 69 6e 28 29 20 75 6e 70 69 6e 73 20 xUnpin() unpins
4be10 74 68 65 20 70 61 67 65 20 72 65 67 61 72 64 6c the page regardl
4be20 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 ess of the numbe
4be30 72 20 6f 66 20 70 72 69 6f 72 20 63 61 6c 6c 73 r of prior calls
4be40 20 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 28 29 .** to xFetch()
4be50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 65 6b ..**.** The xRek
4be60 65 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 ey() method is u
4be70 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 sed to change th
4be80 65 20 6b 65 79 20 76 61 6c 75 65 20 61 73 73 6f e key value asso
4be90 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a ciated with the.
4bea0 2a 2a 20 70 61 67 65 20 70 61 73 73 65 64 20 61 ** page passed a
4beb0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
4bec0 75 6d 65 6e 74 20 66 72 6f 6d 20 6f 6c 64 4b 65 ument from oldKe
4bed0 79 20 74 6f 20 6e 65 77 4b 65 79 2e 20 49 66 20 y to newKey. If
4bee0 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 70 72 65 the cache.** pre
4bef0 76 69 6f 75 73 6c 79 20 63 6f 6e 74 61 69 6e 73 viously contains
4bf00 20 61 6e 20 65 6e 74 72 79 20 61 73 73 6f 63 69 an entry associ
4bf10 61 74 65 64 20 77 69 74 68 20 6e 65 77 4b 65 79 ated with newKey
4bf20 2c 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a , it should be.*
4bf30 2a 20 64 69 73 63 61 72 64 65 64 2e 20 41 6e 79 * discarded. Any
4bf40 20 70 72 69 6f 72 20 63 61 63 68 65 20 65 6e 74 prior cache ent
4bf50 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ry associated wi
4bf60 74 68 20 6e 65 77 4b 65 79 20 69 73 20 67 75 61 th newKey is gua
4bf70 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a 20 74 ranteed not.** t
4bf80 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a o be pinned..**.
4bf90 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 63 ** When SQLite c
4bfa0 61 6c 6c 73 20 74 68 65 20 78 54 72 75 6e 63 61 alls the xTrunca
4bfb0 74 65 28 29 20 6d 65 74 68 6f 64 2c 20 74 68 65 te() method, the
4bfc0 20 63 61 63 68 65 20 6d 75 73 74 20 64 69 73 63 cache must disc
4bfd0 61 72 64 20 61 6c 6c 0a 2a 2a 20 65 78 69 73 74 ard all.** exist
4bfe0 69 6e 67 20 63 61 63 68 65 20 65 6e 74 72 69 65 ing cache entrie
4bff0 73 20 77 69 74 68 20 70 61 67 65 20 6e 75 6d 62 s with page numb
4c000 65 72 73 20 28 6b 65 79 73 29 20 67 72 65 61 74 ers (keys) great
4c010 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c er than or equal
4c020 0a 2a 2a 20 74 6f 20 74 68 65 20 76 61 6c 75 65 .** to the value
4c030 20 6f 66 20 74 68 65 20 69 4c 69 6d 69 74 20 70 of the iLimit p
4c040 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 arameter passed
4c050 74 6f 20 78 54 72 75 6e 63 61 74 65 28 29 2e 20 to xTruncate().
4c060 49 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 If any.** of the
4c070 73 65 20 70 61 67 65 73 20 61 72 65 20 70 69 6e se pages are pin
4c080 6e 65 64 2c 20 74 68 65 79 20 61 72 65 20 69 6d ned, they are im
4c090 70 6c 69 63 69 74 6c 79 20 75 6e 70 69 6e 6e 65 plicitly unpinne
4c0a0 64 2c 20 6d 65 61 6e 69 6e 67 20 74 68 61 74 0a d, meaning that.
4c0b0 2a 2a 20 74 68 65 79 20 63 61 6e 20 62 65 20 73 ** they can be s
4c0c0 61 66 65 6c 79 20 64 69 73 63 61 72 64 65 64 2e afely discarded.
4c0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 73 74 .**.** The xDest
4c0e0 72 6f 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 roy() method is
4c0f0 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 used to delete a
4c100 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 64 cache allocated
4c110 20 62 79 20 78 43 72 65 61 74 65 28 29 2e 0a 2a by xCreate()..*
4c120 2a 20 41 6c 6c 20 72 65 73 6f 75 72 63 65 73 20 * All resources
4c130 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
4c140 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 61 the specified ca
4c150 63 68 65 20 73 68 6f 75 6c 64 20 62 65 20 66 72 che should be fr
4c160 65 65 64 2e 20 41 66 74 65 72 0a 2a 2a 20 63 61 eed. After.** ca
4c170 6c 6c 69 6e 67 20 74 68 65 20 78 44 65 73 74 72 lling the xDestr
4c180 6f 79 28 29 20 6d 65 74 68 6f 64 2c 20 53 51 4c oy() method, SQL
4c190 69 74 65 20 63 6f 6e 73 69 64 65 72 73 20 74 68 ite considers th
4c1a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e [sqlite3_pcach
4c1b0 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 20 69 6e e*].** handle in
4c1c0 76 61 6c 69 64 2c 20 61 6e 64 20 77 69 6c 6c 20 valid, and will
4c1d0 6e 6f 74 20 75 73 65 20 69 74 20 77 69 74 68 20 not use it with
4c1e0 61 6e 79 20 6f 74 68 65 72 20 73 71 6c 69 74 65 any other sqlite
4c1f0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
4c200 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a .** functions..*
4c210 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
4c220 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
4c230 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
4c240 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3b 0a pcache_methods;.
4c250 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 struct sqlite3_p
4c260 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 7b 0a cache_methods {.
4c270 20 20 76 6f 69 64 20 2a 70 41 72 67 3b 0a 20 20 void *pArg;.
4c280 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 int (*xInit)(voi
4c290 64 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 d*);. void (*xS
4c2a0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b hutdown)(void*);
4c2b0 0a 20 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 . sqlite3_pcach
4c2c0 65 20 2a 28 2a 78 43 72 65 61 74 65 29 28 69 6e e *(*xCreate)(in
4c2d0 74 20 73 7a 50 61 67 65 2c 20 69 6e 74 20 62 50 t szPage, int bP
4c2e0 75 72 67 65 61 62 6c 65 29 3b 0a 20 20 76 6f 69 urgeable);. voi
4c2f0 64 20 28 2a 78 43 61 63 68 65 73 69 7a 65 29 28 d (*xCachesize)(
4c300 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c sqlite3_pcache*,
4c310 20 69 6e 74 20 6e 43 61 63 68 65 73 69 7a 65 29 int nCachesize)
4c320 3b 0a 20 20 69 6e 74 20 28 2a 78 50 61 67 65 63 ;. int (*xPagec
4c330 6f 75 6e 74 29 28 73 71 6c 69 74 65 33 5f 70 63 ount)(sqlite3_pc
4c340 61 63 68 65 2a 29 3b 0a 20 20 76 6f 69 64 20 2a ache*);. void *
4c350 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 (*xFetch)(sqlite
4c360 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 69 67 3_pcache*, unsig
4c370 6e 65 64 20 6b 65 79 2c 20 69 6e 74 20 63 72 65 ned key, int cre
4c380 61 74 65 46 6c 61 67 29 3b 0a 20 20 76 6f 69 64 ateFlag);. void
4c390 20 28 2a 78 55 6e 70 69 6e 29 28 73 71 6c 69 74 (*xUnpin)(sqlit
4c3a0 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f 69 64 e3_pcache*, void
4c3b0 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 64 29 3b *, int discard);
4c3c0 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 6b 65 79 . void (*xRekey
4c3d0 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 )(sqlite3_pcache
4c3e0 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 69 67 6e *, void*, unsign
4c3f0 65 64 20 6f 6c 64 4b 65 79 2c 20 75 6e 73 69 67 ed oldKey, unsig
4c400 6e 65 64 20 6e 65 77 4b 65 79 29 3b 0a 20 20 76 ned newKey);. v
4c410 6f 69 64 20 28 2a 78 54 72 75 6e 63 61 74 65 29 oid (*xTruncate)
4c420 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a (sqlite3_pcache*
4c430 2c 20 75 6e 73 69 67 6e 65 64 20 69 4c 69 6d 69 , unsigned iLimi
4c440 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 65 t);. void (*xDe
4c450 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 70 stroy)(sqlite3_p
4c460 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a cache*);.};../*.
4c470 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b ** Undo the hack
4c480 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 that converts f
4c490 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 loating point ty
4c4a0 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 pes to integer f
4c4b0 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 or.** builds on
4c4c0 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f processors witho
4c4d0 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e ut floating poin
4c4e0 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 t support..*/.#i
4c4f0 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
4c500 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
4c510 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 # undef double.#
4c520 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f endif..#ifdef __
4c530 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 cplusplus.} /*
4c540 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 End of the 'exte
4c550 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f rn "C"' block */
4c560 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a .#endif.#endif.